diff --git a/src/docbkx/reference/programming-model/aspectj.xml b/src/docbkx/reference/programming-model/aspectj.xml index 12c6f201a..70324572a 100644 --- a/src/docbkx/reference/programming-model/aspectj.xml +++ b/src/docbkx/reference/programming-model/aspectj.xml @@ -5,7 +5,7 @@ Behind the scenes, Spring Data Graph leverages AspectJ aspects to modify the behavior of simple annotated POJO entities - (see ). Each node entity is backed by a graph node that holds its + (see ). Each node entity is backed by a graph node that holds its properties and relationships to other entities. AspectJ is used for intercepting field access, so that Spring Data Graph can retrieve the information from the entity's backing node or relationship in the database. diff --git a/src/docbkx/reference/programming-model/attachdetach.xml b/src/docbkx/reference/programming-model/attachdetach.xml index dc52d1e41..6eb95c4eb 100644 --- a/src/docbkx/reference/programming-model/attachdetach.xml +++ b/src/docbkx/reference/programming-model/attachdetach.xml @@ -1,36 +1,129 @@
- Detached entities + Detached node entities - By default newly created node entities are in a detached state. When persist() is called on the - entity it is attached to the graph store and its properties and relationships are persisted as well. Changing - an attached entity inside a transaction will write through the changes to the datastore. Whenever an entity - is changed outside of a transaction it will be considered detached. The changed data is stored in the entity - itself and not written back to the datastore. + Node entities can be in two different persistence state: attached or detached. By default, newly created node + entities are in the detached state. When persist() is called on the entity, it becomes + attached to the graph, and its properties and relationships are stores in the database. If + persist() is not called within a transaction, it automatically creates an implicit + transaction for the operation. - All entities that are returned by library functions are initially in an attached state. Changing them outside - of a transaction detaches them. For writing the changes back it is necessary to persist() them - again. + Changing an attached entity inside a transaction will immediately write through the changes to + the datastore. Whenever an entity is changed outside of a transaction it becomes detached. The + changes are stored in the entity itself until the next call to persist(). - Persisting an entity not only persists that single entity but will traverse its existing and new relationships - and persist the cluster of detached entities that it is part of. The borders of this cluster are formed by - attached entities. The persist operation creates its own, implicit transaction. When it is called withina - external transaction it participates otherwise it is an atomic operation. + All entities returned by library functions are initially in an attached state. + Just as with any other entity, changing them outside of a transaction detaches them, and they + must be reattached with persist() for the data to be saved. - - Please keep in mind that the session handling behaviour is still heavily developed. The defaults and also - other aspects of the behaviour are likely to change in subsequent releases. At the moment there is no support - for the creation of relationships outside of transactions and also more complex operations like creating - whole subgraphs outside of transactions is not supported. - - --> + + + + + + + Persisting entities + + +
+ Relating detached entities + + As mentioned above, an entity simply created with the new keyword starts out detached. + It also has no state assigned to it. If you create a new entity with new and then throw + it away, the database won't be touched at all. + + + Now consider this scenario: + + Relationships outside of transactions + + + + + Neither the actor nor the movie has been assigned a node in the graph. If we were to call + movie.persist(), then Spring Data Graph would first create a node for the movie. + It would then note that there is a relationship to an actor, so it would call actor.persist() + in a cascading fashion. Once the actor has been persisted, it will create the relationship + from the movie to the actor. All of this will be done atomically in one transaction. + + + Important to note here is that if actor.persist() is called instead, then only + the actor will be persisted. The reason for this is that the actor entity knows nothing about + the movie entity. It is the movie entity that has the reference to the actor. Also note that + 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. + + + 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 persist() + is however only cascaded to related entity fields that have been modified. + + + In the following example, the actor and the movie are both attached entites, having both been + previously persisted to the graph: + + Cascade for modified fields + + + In this case, even though the movie has a reference to the actor, the name change on the actor + will not be persisted by the call to movie.persist(). The reason for this is, as + mentioned above, that cascading will only be done for fields that have been modified. Since the + movie.topActor field has not been modified, it will not cascade the persist operation + to the actor. + +
+ + + + + + + + + + + + + + + + + + + + + + + +
diff --git a/src/docbkx/reference/programming-model/beanvalidation.xml b/src/docbkx/reference/programming-model/beanvalidation.xml index 8ce969cbe..344edef98 100644 --- a/src/docbkx/reference/programming-model/beanvalidation.xml +++ b/src/docbkx/reference/programming-model/beanvalidation.xml @@ -3,22 +3,24 @@
Bean validation (JSR-303) - Spring Data Graph supports property based validation support. So, whenever a property is changed, it is - checked against the annotated constraints (.e.g @Min, @Max, @Size, etc). - Validation errors throw a ValidationException. For evaluating the constraints the validation support that - comes with Spring is used. To use it a validator has to be registered with the GraphDatabaseContext, if there - is none, no validation will be performed (any registered Validator or (Local)ValidatorFactoryBean will be - used). + Spring Data Graph supports property-based validation support. When a property is changed, it is + checked against the annotated constraints, e.g. @Min, @Max, + @Size, etc. Validation errors throw a ValidationException. The validation + support that comes with Spring is used for evaluating the constraints. To use this feature, a validator + has to be registered with the GraphDatabaseContext. - + Bean validation + + +
diff --git a/src/docbkx/reference/programming-model/indexing.xml b/src/docbkx/reference/programming-model/indexing.xml index 8d10a60b7..a391c853e 100644 --- a/src/docbkx/reference/programming-model/indexing.xml +++ b/src/docbkx/reference/programming-model/indexing.xml @@ -29,7 +29,8 @@ package. - The indexes can be queried by using a repository (see ). + The indexes can be queried by using a repository (see + ). Typically, the repository is an instance of org.springframework.data.graph.neo4j.repository.DirectGraphRepositoryFactory. The methods findByPropertyValue() and findAllByPropertyValue() work on @@ -45,7 +46,8 @@ class Person { @Indexed int age; } -GraphRepository graphRepository = graphRepositoryFactory.createGraphRepository(Person.class); +GraphRepository graphRepository = graphRepositoryFactory + .createGraphRepository(Person.class); // Exact match, in named index Person mark = graphRepository.findByPropertyValue("people", "name", "mark"); @@ -84,7 +86,8 @@ class Person { @Indexed(indexName = "person-name", fulltext=true) String name; } -GraphRepository graphRepository = graphRepositoryFactory.createGraphRepository(Person.class); +GraphRepository graphRepository = graphRepositoryFactory + .createGraphRepository(Person.class); Person mark = graphRepository.findAllByQuery("people-search", "name", "ma*"); ]]> diff --git a/src/docbkx/reference/programming-model/node-entities.xml b/src/docbkx/reference/programming-model/node-entities.xml index 4b32cc494..98ead57b0 100644 --- a/src/docbkx/reference/programming-model/node-entities.xml +++ b/src/docbkx/reference/programming-model/node-entities.xml @@ -9,92 +9,90 @@
@NodeEntity: The basic building block - 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 entity. - - If the partial - parameter is set to true, this entity takes part in a cross-store setting /) - where only the specifically annotated parts of the entity not handled by JPA will be mapped to the graph store. + The @NodeEntity annotation is used to turn a POJO class into an entity backed by a node + in the graph database. Fields on the entity are by default mapped to properties of the node. Fields + referencing other node entities (or collections thereof) are linked with relationships. If the + useShortNames attribute overridden to false, the property and relationship names will + have the class name of the entity prepended. - Entity fields can be annotated with @GraphProperty, @RelatedTo, @RelatedToVia, @Indexed, @GraphId and - @GraphTraversal. + + If the partial 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 + for more information. - - Simple Node Entity - + Entity fields can be annotated with @GraphProperty, @RelatedTo, + @RelatedToVia, @Indexed, @GraphId and + @GraphTraversal. + + + Simple node entity + - +
+
- @GraphProperty: Optional Annotation for Property Fields - It is not necessary to annotate fields as they are persisted by default; all fields that contain primitive - values are persisted directly to the graph. All fields - convertible to String using the Spring conversion services will be stored as a string. - (Spring Data Graph adds a custom conversion factory that comes with converters for Enums and Dates). + @GraphProperty: Optional annotation for property fields + + It is not necessary to annotate data fields, as they are persisted by default; all fields that + contain primitive values are persisted directly to the graph. All fields convertible to String + using the Spring conversion services will be stored as a string. Spring Data Graph includes a + custom conversion factory that comes with converters for Enums and Dates. Transient fields are not persisted. - This annotation is mainly used for cross-store persistence. + + + 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 + with @GraphProperty.
@Indexed: Making entities searchable by field value - The @Indexed annotation can be declared on fields that are intended to be indexed by the Neo4j - indexing facilities, triggered by value modification. - The resulting index can be used to later retrieve nodes or relationships that contain a certain property - value (for example a name). Often an index is used to establish the start node for a traversal. - Indexes are accessed by a Repository for a particular node or relationship entity, created via a - DirectGraphRepositoryFactory. - - GraphDatabaseContext exposes the indexes for Nodes and Relationships via the getIndex method. - Index names default to the domain class - name, but can also be named (indexName attribute)individually to reflect domain concepts. - be named, for instance to keep separate domain concepts in separate indexes. - - - Numerical values are indexed as such by default, allowing for range queries. - Fulltext indexing is also possible by setting the fulltext attribute to true. For details see - the indexing section . + The @Indexed annotation can be declared on fields that are intended to be indexed by the Neo4j + indexing facilities. The resulting index can be used to later retrieve nodes or relationships + that contain a certain property value, e.g. a name. Often an index is used to establish the start + node for a traversal. Indexes are accessed by a repository for a particular node or relationship + entity type. See and + for more information.
- @GraphTraversal: fields providing direct access to traversal results - The @GraphTraversal annotation leverages the delegation infrastructure used by the Spring Data Graph - aspects. It provides dynamic fields which, when accessed, return an Iterable of NodeEntities that are - the result of a traversal starting at the current NodeEntity. The TraversalDescription used for this - is created by a TraversalDescriptionBuilder whose class is referred to by the traversalBuilder - attribute of the annotation. The class of the expected NodeEntities is provided with the + @GraphTraversal: fields as traversal result views + + The @GraphTraversal annotation leverages the delegation infrastructure used by the + Spring Data Graph aspects. It provides dynamic fields which, when accessed, return an Iterable + of node entities that are the result of a traversal starting at the entity containing the field. + The TraversalDescription used for this is created by the + FieldTraversalDescriptionBuilder class defined by the traversalBuilder + attribute. The class of the resulting node entities must be provided with the elementClass attribute. - - @GraphTraversal in a Node Entity - + + @GraphTraversal from a node entity + people; + @GraphTraversal(traversalBuilder = PeopleTraversalBuilder.class, + elementClass = Person.class, params = "persons") + private Iterable people; -private static class PeopleTraversalBuilder implements FieldTraversalDescriptionBuilder { - @Override - public TraversalDescription build(NodeBacked start, Field field, String...params) { - return new TraversalDescriptionImpl() - .relationships(DynamicRelationshipType.withName(params[0])) - .filter(Traversal.returnAllButStartNode()); + private static class PeopleTraversalBuilder implements FieldTraversalDescriptionBuilder { + @Override + public TraversalDescription build(NodeBacked start, Field field, String... params) { + return new TraversalDescriptionImpl() + .relationships(DynamicRelationshipType.withName(params[0])) + .filter(Traversal.returnAllButStartNode()); + } } } -} ]]> - - +
\ No newline at end of file diff --git a/src/docbkx/reference/programming-model/relationships.xml b/src/docbkx/reference/programming-model/relationships.xml index 626821545..083fe52de 100644 --- a/src/docbkx/reference/programming-model/relationships.xml +++ b/src/docbkx/reference/programming-model/relationships.xml @@ -9,7 +9,7 @@ Spring Data Graph has special support to represent Neo4j relationships as entities too, but it is often not needed. -
+
@RelatedTo: Connecting node entities Every field of a node entity that references one or more other node entities is backed by relationships @@ -45,7 +45,8 @@ public class Movie { mostPaidIn; @RelatedTo(type = "ACTS_IN", elementClass = Movie.class) diff --git a/src/docbkx/reference/programming-model/repositories.xml b/src/docbkx/reference/programming-model/repositories.xml index 3fbec2230..1d80a9e07 100644 --- a/src/docbkx/reference/programming-model/repositories.xml +++ b/src/docbkx/reference/programming-model/repositories.xml @@ -1,6 +1,6 @@ -
+
CRUD with repositories The repositories provided by Spring Data Graph build on the composable repository infrastructure @@ -105,7 +105,8 @@ Using GraphRepositories graphRepository = graphRepositoryFactory.createGraphRepository(Person.class); +GraphRepository graphRepository = graphRepositoryFactory + .createGraphRepository(Person.class); Person michael = graphRepository.save(new Person("Michael", 36)); @@ -140,8 +141,9 @@ Iterable davesFriends = graphRepository.findAllByTraversal(dave, public interface PersonRepository extends GraphRepository, PersonRepositoryExtension {} // alternatively select some of the required repositories individually -public interface PersonRepository extends CRUDGraphRepository, IndexQueryExecutor, - TraversalQueryExecutor, PersonRepositoryExtension {} +public interface PersonRepository extends CRUDGraphRepository, + IndexQueryExecutor, TraversalQueryExecutor, + PersonRepositoryExtension {} // provide a custom extension if needed public interface PersonRepositoryExtension { @@ -156,8 +158,10 @@ public class PersonRepositoryImpl implements PersonRepositoryExtension { } } -// configure the repositories, preferably via the datagraph:repositories namespace (graphDatabaseContext reference is optional) - +// configure the repositories, preferably via the datagraph:repositories namespace +// (graphDatabaseContext reference is optional) + // have it injected @Autowired diff --git a/src/docbkx/reference/programming-model/typerepresentationstrategy.xml b/src/docbkx/reference/programming-model/typerepresentationstrategy.xml index ce28c4304..83f38ce1e 100644 --- a/src/docbkx/reference/programming-model/typerepresentationstrategy.xml +++ b/src/docbkx/reference/programming-model/typerepresentationstrategy.xml @@ -1,7 +1,7 @@
- Entity types stored + Entity type representation There are several ways to represent the Java type hierarchy of the data model in the graph. In general, for all node and relationship entities, type information is needed to perform certain repository operations. Some of