From c499f8d40f9a01d9e1be131711fe5238e838708b Mon Sep 17 00:00:00 2001 From: Mark Pollack Date: Fri, 25 Feb 2011 18:12:30 -0300 Subject: [PATCH] small documentation changes --- src/docbkx/introduction/introduction.xml | 2 +- src/docbkx/introduction/why-sd-graph.xml | 4 +-- src/docbkx/neo4j.xml | 13 ++++----- src/docbkx/programming-model.xml | 35 ++++++++++++------------ src/docbkx/setup.xml | 12 ++++++-- 5 files changed, 36 insertions(+), 30 deletions(-) diff --git a/src/docbkx/introduction/introduction.xml b/src/docbkx/introduction/introduction.xml index 5df0fa714..993c602a5 100644 --- a/src/docbkx/introduction/introduction.xml +++ b/src/docbkx/introduction/introduction.xml @@ -8,7 +8,7 @@ It explains the underlying concepts, usage, infrastructure of the framework and the semantics for the used graph database. - For an introduction to graph databases or Spring, or Spring Data examples, please refer to + For an introduction to graph databases, Spring, or Spring Data examples, please refer to . This documentation refers only to Spring Data Graph and assumes that the reader is familiar with Spring concepts. diff --git a/src/docbkx/introduction/why-sd-graph.xml b/src/docbkx/introduction/why-sd-graph.xml index acc37aeb9..83121e473 100644 --- a/src/docbkx/introduction/why-sd-graph.xml +++ b/src/docbkx/introduction/why-sd-graph.xml @@ -25,13 +25,13 @@ The Spring Data Graph (or 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. + common patterns and idioms that are well known in the Spring Framework community such as declarative transaction managment. 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. - A special use case of Spring Data Graph is the cross-store solution that can extend + A special use case of Spring Data Graph is the cross-store functionality that can extend existing JPA data models with new, graph database backed parts (properties, entities, relationships). These parts are stored exclusively in the graph database while being transparently integrated with the JPA entities. This enables easy and seamless addition of new features diff --git a/src/docbkx/neo4j.xml b/src/docbkx/neo4j.xml index 331d0a279..a8836d56e 100644 --- a/src/docbkx/neo4j.xml +++ b/src/docbkx/neo4j.xml @@ -26,16 +26,16 @@
GraphDatabaseService - The GraphDatabaseService is the API interface to the storage engine. It provides access to create and retrieve Nodes and Relationships, an IndexManager, lifecycle and transactional methods and more. + The interface org.neo4j.graphdb.GraphDatabaseService provides access to the storage engine. Its features include creating and retrieving Nodes and Relationships, managing indexes, via an IndexManager, database lifecycle callbacks, transation management and more. - The EmbeddedGraphDatabaseService is running within the current Java application for highest performance and tightest integration. There are other, + The EmbeddedGraphDatabaseService is an implementation of GraphDatabaseService that is used to embed Neo4j in a Java application. This implmentation is used so as to provide the highest and tightest integration. There are other, remote implementations that provide access to Neo4j stores via REST.
Creating Nodes and Relationships - Using the API of GraphDatabaseService it is easy to create nodes and relate them to each other. Relationships are named. Both nodes and relationships can have properties. Property values can be of primitive Java types and Strings as well as byte arrays for binary data or arrays of other Java primitives or Strings. - Node creation and modification has to happen within a transaction, while reading from the graph store can be done without a transaction. + Using the API of GraphDatabaseService it is easy to create nodes and relate them to each other. Relationships are named. Both nodes and relationships can have properties. Property values can be primitive Java types and Strings, byte arrays for binary data, or arrays of other Java primitives or Strings. + Node creation and modification has to happen within a transaction, while reading from the graph store can be done with or without a transaction. - Spring Data Graph provides auto-indexing via the + Note: Spring Data Graph provides auto-indexing via the @Indexed annotation, while this still is a manual process when using the Neo4j API. diff --git a/src/docbkx/programming-model.xml b/src/docbkx/programming-model.xml index a58f1b3d0..a7932b8e8 100644 --- a/src/docbkx/programming-model.xml +++ b/src/docbkx/programming-model.xml @@ -23,13 +23,13 @@
Using annotations to define POJO entities and relationships - Entities are declared using the @NodeEntity annotation. Relationship entities use the @RelationshipEntity annotation instead. + Entities are declared using the @NodeEntity annotation. Relationship entities use the @RelationshipEntity annotation.
Entities with @NodeEntity - This annotation is used to declare a POJO entity to be backed by a node in the graph store. Its simple fields + The @NodeEntity annotation is used to declare a POJO entity to be backed by a node in the graph store. Simple fields on the entity are mapped by default to properties of the node. Object references to other NodeEntities (whether single or Collection) are mapped via relationships. If the annotation parameter useShortNames - is set to false the properties and relationship names used will be prepended with the class name of the + is set to false, the properties and relationship names used will be prepended with the class name of the entity. If the parameter fullIndex is set to true, all fields of the entity will be indexed. If the partial parameter is set to true, this entity takes part in a cross-store setting where only the parts of the entity not handled by JPA will be mapped to the graph store. @@ -49,8 +49,7 @@ public class Movie { node entities, either by @RelatedToVia fields or by the relateTo or getRelationshipTo methods. Relationship entities may contain fields that are mapped to properties and two special fields that are - annotated with @StartNode and @EndNode which point to the start and end node entities respectively (and - are read only). + annotated with @StartNode and @EndNode which point to the start and end node entities respectively. These fields are treated as read only fields. Relationships to other NodeEntities are mapped to graph relationships. Those can either be single relationships (1:1) or multiple relationships (1:n). In most cases single relationships to other - node entities don't have to be annotated as Spring Data Graph can extract all needed information from the field + node entities don't have to be annotated as Spring Data Graph can extract all necessary information from the field using reflection. In the case of multiple relationships, the elementClass parameter of @RelatedTo must be specified because of type erasure. The direction (default OUTGOING) and type @@ -320,14 +319,14 @@ for (Person person : finder.findAllByProperyValue("occupation","developer")) { Much like a resultset a path contains nodes() and relationships() starting at a startNode() and ending with a endNode(), the lastRelationship() is also available separately. - Using this Path abstraction also wraps results that contain just nodes or relationships. + The Path abstraction also wraps results that contain just nodes or relationships. Using implementations of PathMapper<T> and PathMapper.WithoutResult (comparable with RowMapper and - RowCallbackHandler) the paths can be converted to other Java or domain objects. + RowCallbackHandler) the paths can be converted to Java objects. Query methods either take a field / value combination to look for exact matches in the index or a lucene query object or string to handle more complex queries. - Traversal methods are the bread and butter of graph operations. So they are fully supported in the Neo4jTemplate. + Traversal methods are the bread and butter of graph operations. As such, they are fully supported in the Neo4jTemplate. The traverseNext method traverses to the direct neighbours of the start node filtering the relationships according to its parameters. @@ -356,20 +355,19 @@ for (Person person : finder.findAllByProperyValue("occupation","developer")) {
Indexing - The Neo4j graph database can use different index provides for exact lookups and fulltext searches. By now - lucene is used as a index provider implementation. There is support for distinct indexes for nodes and relationships - which can be configured to be of fulltext or exact types. Nodes and Relationships and the indexed field-value combinations - have to be added manually to the appropriate index. + The Neo4j graph database can use different index providers for exact lookups and fulltext searches. Lucene is used as a index provider implementation. There is support for distinct indexes for nodes and relationships + which can be configured to be of fulltext or exact types. - Within Spring Data Graph this is eased by having an @Indexed annotation on entity fields that updates the index on + Using the standard Neo4j API, Nodes and Relationships and their indexed field-value combinations + have to be added manually to the appropriate index. When using Spring Data Graph, this task is simplified by eased by applying an @Indexed annotation on entity fields. This will result in updates to the index on every change. Numerical fields are indexed numerically so that they are available for range queries. All other fields are indexed with their string representation. The @Indexed annotation can also set the index-name to be used. - If it is put on top of the entity class the index-name for the whole entity is preset to that value. Not providing + If @Indexed annotates the entity class, the index-name for the whole entity is preset to that value. Not providing index names defaults them to "node" and "relationship" respectively. - Query access to the index happens with the Node- and RelationshipFinders that are created via the FinderFactory. + Query access to the index happens with the Node- and RelationshipFinders that are created via an instance of org.springframework.data.graph.neo4j.finder.FinderFactory. The methods findByPropertyValue and findAllByPropertyValue work on the exact indexes and return the first or all matches. To do range queries, use findAllByRange (please note that currently both values are inclusive). @@ -424,8 +422,9 @@ for (Person middleAgedDeveloper : finder.findAllByRange(null, "age", 20, 40)) { Spring Data Graph integrates with transaction managers configured using Spring. The simplest scenario of just running the graph database uses a SpringTransactionManager provided by the Neo4j kernel to be used - with Spring's JtaTransactionManager. The explicit configuration given below is encoded in the Neo4jConfiguration - configuration bean so as a user one doesn't have to provide it. + with Spring's JtaTransactionManager. + +Note: The explicit XML configuration given below is encoded in the Neo4jConfiguration configuration bean that uses Spring's @Configuration functioanlity. This simplifies the configuration. An example is shown further below. diff --git a/src/docbkx/setup.xml b/src/docbkx/setup.xml index 985f5f579..c8a823980 100644 --- a/src/docbkx/setup.xml +++ b/src/docbkx/setup.xml @@ -180,8 +180,16 @@
Java based Configuration - That's why Spring Data Graph provides a Spring Java Config class (annotated with @Config) Neo4jConfiguration that takes care of all that. The only - thing that must be provided in the custom Spring config is the GraphDatabaseService configured with a datastore directory. + You can also configure Spring Data Graph using Java based bean metadata. + For those not familiar with how to configure the Spring + container using Java based bean metadata instead of XML based metadata + see the high level introduction in the reference docs here as well as the detailed documentation here. + + +To help configure Spring Data Graph using Java based bean metadata the class Neo4jConfiguration is registerd with the context either explicitly in the XML config or via classpath scanning for classes that have the @Configuration annotation. The only thing that must be provided in addition is the GraphDatabaseService configured with a datastore directory. The example below shows using XML to register the Neo4jConfiguration @Configuration class as well as Spring's ConfigurationClassPostProcessor that transforms the @Configuration class to bean definitions. ...