From a54a3b724f41d582b0ab642a55c78115c7ee6393 Mon Sep 17 00:00:00 2001 From: David Montag Date: Thu, 7 Apr 2011 23:44:16 -0700 Subject: [PATCH] Edits for reference aspectj chapter, and for introduced methods. --- src/docbkx/reference/aspectj-intro.xml | 2 +- .../reference/programming-model/aspectj.xml | 56 +++++++-------- .../programming-model/introducedmethods.xml | 69 +++++++++++++------ 3 files changed, 77 insertions(+), 50 deletions(-) diff --git a/src/docbkx/reference/aspectj-intro.xml b/src/docbkx/reference/aspectj-intro.xml index bdf75c6a9..787fd2910 100644 --- a/src/docbkx/reference/aspectj-intro.xml +++ b/src/docbkx/reference/aspectj-intro.xml @@ -1,6 +1,6 @@ - + AspectJ introduction The object graph mapper of Spring Data Graph relies heavily on AspectJ. AspectJ is the Java implementation of diff --git a/src/docbkx/reference/programming-model/aspectj.xml b/src/docbkx/reference/programming-model/aspectj.xml index 786b1c02f..facbdb39c 100644 --- a/src/docbkx/reference/programming-model/aspectj.xml +++ b/src/docbkx/reference/programming-model/aspectj.xml @@ -2,36 +2,37 @@
Overview of the AspectJ support - Behind the scenes Spring Data Graph leverages AspectJ - () - aspects to modify the behavior of simple POJO entities to be able to be backed by a graph store. - Each node entity is backed by a graph node that holds its properties and relationships to other entities. - AspectJ is used to intercept field access and to retrieve the information from the backing node - (either its properties or relationships or dynamic traversals starting from the node). - - For relationship entities the fields are similarly mapped to properties. - There are two specially annotated fields for the start and the end node of the relationship. + + 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 + 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. - The aspect introduces some internal fields and some public methods () - to the entities for accessing the backing - state via getPersistentState() and creating relationships with relateTo - and retrieving relationship entities via getRelationshipTo. It also introduces graphRepository methods like - find(Class<? extends NodeEntity>, TraversalDescription) - and equals and hashCode delegation. + The aspect introduces some internal fields and some public methods + (see ) in the entities, such as + entity.getPersistentState() and entity.relateTo. + It also introduces repository methods like + find(Class<? extends NodeEntity>, TraversalDescription), + and equals() and hashCode delegation, making equals() + honor the backing state. - Spring Data Graph internally uses an abstraction called EntityState that the field access and instantiation - advices of the aspect delegate to, keeping the aspect code very small and focused to the pointcuts and - delegation code. The EntityState then uses a number of FieldAccessorFactories - to create a FieldAccessor instance per field that does the specific handling needed for the concrete field type. + Spring Data Graph internally uses an abstraction called EntityState that the field + access and instantiation advices of the aspect delegate to. This way, the aspect code is kept to a + minimum, focusing mainly on the pointcuts and delegation code. The EntityState then uses + a number of FieldAccessorFactories to create a FieldAccessor 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.
- IDE-AspectJ Support + AspectJ IDE support - As Spring Data Graph uses some advanced aspects of AspectJ, there might be issues with IDE reporting errors - where there are none. Features that might be reported are: introduction of methods to interfaces, declaration - of additional interfaces for annotated classes, generified introduced methods. + As Spring Data Graph uses some advanced features of AspectJ, users may experience issues with + their IDE reporting errors where there in fact are none. Features that might be reported wrongfully + include: introduction of methods to interfaces, declaration of additional interfaces for annotated + classes, and generified introduced methods. Eclipse and STS support AspectJ via the AJDT plugin which can be installed from the update-site: @@ -40,10 +41,11 @@ http://download.eclipse.org/tools/ajdt/36/dev/update). - The AspectJ support in IntelliJ IDEA lacks some of the features. JetBrains is working to improve the situation - with the upcoming 10.5 release of the IDE (which is currently available as EAP). Building the project with - Ajc works in the IDE (Options -> Compiler -> Java-Compiler should show Ajc, please add - 512 MB RAM for the compiler to run). + The AspectJ support in IntelliJ IDEA lacks some of the features. JetBrains is working on improving + the situation in their upcoming 10.5 release of their popular IDE. Their latest work is available + under their early access program (EAP). Building the project with the AspectJ compiler + ajc works in IDEA (Options -> Compiler -> Java Compiler should show ajc). Make sure to + give the compiler at least 512 MB of RAM.
\ No newline at end of file diff --git a/src/docbkx/reference/programming-model/introducedmethods.xml b/src/docbkx/reference/programming-model/introducedmethods.xml index cbf92f091..18ea4dc33 100644 --- a/src/docbkx/reference/programming-model/introducedmethods.xml +++ b/src/docbkx/reference/programming-model/introducedmethods.xml @@ -3,89 +3,114 @@
Methods added to entity classes - The node and relationship aspects introduce (via ITD - inter type declaration) several methods to the - entities that make common tasks easier. + The node and relationship aspects introduce (via AspectJ ITD - inter type declaration) several + methods to the entities. - persisting the node-entity initially and after changes outside of a transaction, - persist participates in a transaction or creates its own implict transaction. + + Persisting the node entity after creation and after changes outside of a transaction. + Participates in an open transaction, or creates its own implicit transaction otherwise. nodeEntity.persist() - accessing node and relationship ids + + Accessing node and relationship IDs + - nodeEntity.getNodeId() and relationshipEntity.getRelationshipId() + nodeEntity.getNodeId() and relationshipEntity.getRelationshipId() - accessing the node or relationship backing the entity + + Accessing the node or relationship backing the entity + entity.getPersistentState() - equals and hashcode are delegated to the underlying state + + equals() and hashCode() are delegated to the underlying state + - entity.equals() and entity.hashCode() + entity.equals() and entity.hashCode() - creating relationships to a target node entity and returning the relationship-entity instance + + Creating relationships to a target node entity, and returning the relationship entity instance + nodeEntity.relateTo(targetEntity, relationshipClass, relationshipType) - retrieving a single relationship-entity + + Retrieving a single relationship entity + - nodeEntity.getRelationshipTo(targetEnttiy, relationshipClass, relationshipType) + nodeEntity.getRelationshipTo(targetEntity, relationshipClass, relationshipType) - creating relationships to a target node entity and returning the relationship + + Creating relationships to a target node entity and returning the relationship + nodeEntity.relateTo(targetEntity, relationshipType) - retrieving a single relationship + + Retrieving a single relationship + nodeEntity.getRelationshipTo(targetEnttiy, relationshipType) - removing a single relationship + + Removing a single relationship + nodeEntity.removeRelationshipTo(targetEntity, relationshipType) - remove the node entity, its relationships and index entries + + Remove the node entity, its relationships, and all index entries for it + - entity.remove() + nodeEntity.remove() and relationshipEntity.remove() - projecting to a different target type + + Project entity to a different target type, using the same backing state + entity.projectTo(targetClass) - traversing, starting at the current node, returns end-nodes of traversal converted to provided type + + Traverse, starting from the current node. Returns end nodes of traversal converted to + the provided type. + nodeEntity.findAllByTraversal(targetType, traversalDescription) - traversing, starting at the current node, returns EntityPath's of the traversal result - bound to the provided start and end-node-entity types + + Traverse, starting from the current node. Returns EntityPaths of the traversal result + bound to the provided start and end-node-entity types - Iterable<EntityPath> findAllPathsByTraversal(traversalDescription) + Iterable<EntityPath> findAllPathsByTraversal(traversalDescription)