From c25f9ddbbc9e98c229989a253d805931fcbd8c0b Mon Sep 17 00:00:00 2001
From: Michael Hunger <github@jexp.de>
Date: Fri, 18 Mar 2011 19:17:40 +0100
Subject: [PATCH] updated docs, started with aspectj

---
 src/docbkx/reference/aspectj-intro.xml | 30 +++++++++++++++++++++++++-
 src/docbkx/reference/performance.xml   |  3 ++-
 src/docbkx/tutorial/setup.xml          | 18 ++++++----------
 3 files changed, 38 insertions(+), 13 deletions(-)

diff --git a/src/docbkx/reference/aspectj-intro.xml b/src/docbkx/reference/aspectj-intro.xml
index c4d689ca5..28a502536 100644
--- a/src/docbkx/reference/aspectj-intro.xml
+++ b/src/docbkx/reference/aspectj-intro.xml
@@ -3,6 +3,34 @@
 <chapter id="reference_aspectj-intro">
     <title>AspectJ introduction</title>
     <para>
-        ...
+        The object graph mapper of Spring Data Graph relies heavily on AspectJ. AspectJ is the Java implementation of
+        the Aspect Oriented Programming paradigm that allows easy extraction and controlled application of so called
+        cross cutting concerns. Cross cutting concerns are repetitive tasks in a system (e.g. logging, security,
+        auditing, caching, transaction scoping) that are difficult to extract using the normal OO paradigms. The means
+        of the OO paradigm, of subclassing, polymorphism, overriding and delegation are still very cumbersome to use
+        with many of those concerns applied in the codebase. Also the flexibility is limited or would add quite a number
+        of configuration options or parameters.
+    </para>
+    <para>
+        The learning curve for the aspectj pointcut language is quite steep but the developer who uses Spring Data Graph
+        will not be confronted with that. They will just reap the benefits of not having to hook into some framework
+        mechanism and not being required to extend some framework superclass using up the only inheritance link that Java
+        offers.
+    </para>
+    <para>
+        That's why aspectj uses a declarative approach, defining the concrete concern as an advice, which is just
+        the piece of code that contains the implementation of the concern. An advice can  for instance
+        be applied before, after, instead a method or constructor call or a variable access. The point of application
+        is declared using AspectJ's expressive "pointcut" language that is able to express any place within a code structure
+        or flow.
+    </para>
+    <para>
+        AspectJ has even more features. It is able to introduce new methods, fields, annotations, interfaces and superclasses
+        to existing classes and then even apply the classic AOP advices to those introduced elements. This process is called &quot;Inter Type
+        Declaration (ITD)&quot;. The keyword used for that is "declare".
+    </para>
+    <para>
+        Spring Data Graph uses both mechanisms internally. First, when encountering <code>@NodeEntity</code> or <code>@RelationshipEntity</code>
+        annotations it introduces a new interface <code>NodeBacked</code>.
     </para>
 </chapter>
diff --git a/src/docbkx/reference/performance.xml b/src/docbkx/reference/performance.xml
index 5bfa652d6..28e467699 100644
--- a/src/docbkx/reference/performance.xml
+++ b/src/docbkx/reference/performance.xml
@@ -29,7 +29,8 @@
             use (method, class or jsp for example).
         </para>
         <para>
-            Most of the overhead comes from the use of the Java Reflection API, which is leveraged to provide information about Annotations, Fields and Constructors.
+            Most of the overhead comes from the use of the Java Reflection API, which is leveraged to provide
+            information about Annotations, Fields and Constructors.
             Some of the information is already cached by the JVM and the library, so that only the first access gets a
             performance penalty.
         </para>
diff --git a/src/docbkx/tutorial/setup.xml b/src/docbkx/tutorial/setup.xml
index 48be97832..16ff47172 100644
--- a/src/docbkx/tutorial/setup.xml
+++ b/src/docbkx/tutorial/setup.xml
@@ -94,19 +94,15 @@
         <programlisting language="xml"><![CDATA[
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <beans xmlns="http://www.springframework.org/schema/beans"
-    xmlns:aop="http://www.springframework.org/schema/aop"
     xmlns:context="http://www.springframework.org/schema/context"
-    xmlns:jee="http://www.springframework.org/schema/jee"
     xmlns:tx="http://www.springframework.org/schema/tx"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xmlns:task="http://www.springframework.org/schema/task"
-    xmlns:p="http://www.springframework.org/schema/p"
-    xsi:schemaLocation="http://www.springframework.org/schema/jee http://www.springframework.org/schema/jee/spring-jee-3.0.xsd
-		http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-3.0.xsd
-		http://www.springframework.org/schema/task http://www.springframework.org/schema/task/spring-task-3.0.xsd
-		http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
-		http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-3.0.xsd
-		http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd">
+    xsi:schemaLocation="
+	http://www.springframework.org/schema/beans
+	http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
+	http://www.springframework.org/schema/tx
+	http://www.springframework.org/schema/tx/spring-tx-3.0.xsd
+	http://www.springframework.org/schema/context
+	http://www.springframework.org/schema/context/spring-context-3.0.xsd">
 
  <context:annotation-config/>
  <context:spring-configured/>