Polish AOP chapter

framework-docs/src/docs/asciidoc/core/core-aop.adoc

@@ -224,7 +224,7 @@ as needed.
 
 The @AspectJ support can be enabled with XML- or Java-style configuration. In either
 case, you also need to ensure that AspectJ's `aspectjweaver.jar` library is on the
-classpath of your application (version 1.8 or later). This library is available in the
+classpath of your application (version 1.9 or later). This library is available in the
 `lib` directory of an AspectJ distribution or from the Maven Central repository.
 
 
@@ -274,10 +274,10 @@ import the tags in the `aop` namespace.
 With @AspectJ support enabled, any bean defined in your application context with a
 class that is an @AspectJ aspect (has the `@Aspect` annotation) is automatically
 detected by Spring and used to configure Spring AOP. The next two examples show the
-minimal definition required for a not-very-useful aspect.
+minimal steps required for a not-very-useful aspect.
 
-The first of the two example shows a regular bean definition in the application
-context that points to a bean class that has the `@Aspect` annotation:
+The first of the two examples shows a regular bean definition in the application context
+that points to a bean class that is annotated with `@Aspect`:
 
 [source,xml,indent=0,subs="verbatim,quotes"]
 ----
@@ -286,10 +286,10 @@ context that points to a bean class that has the `@Aspect` annotation:
 	</bean>
 ----
 
-The second of the two examples shows the `NotVeryUsefulAspect` class definition,
-which is annotated with the `org.aspectj.lang.annotation.Aspect` annotation;
+The second of the two examples shows the `NotVeryUsefulAspect` class definition, which is
+annotated with `@Aspect`:
 
-[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages"]
+[source,java,indent=0,subs="verbatim,quotes",role="primary",chomp="-packages",fold="none"]
 .Java
 ----
 	package org.xyz;
@@ -300,7 +300,7 @@ which is annotated with the `org.aspectj.lang.annotation.Aspect` annotation;
 	public class NotVeryUsefulAspect {
 	}
 ----
-[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages"]
+[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary",chomp="-packages",fold="none"]
 .Kotlin
 ----
 	package org.xyz
@@ -441,13 +441,7 @@ Spring AOP also supports an additional PCD named `bean`. This PCD lets you limit
 the matching of join points to a particular named Spring bean or to a set of named
 Spring beans (when using wildcards). The `bean` PCD has the following form:
 
-[source,java,indent=0,subs="verbatim,quotes",role="primary"]
-.Java
-----
-	bean(idOrNameOfBean)
-----
-[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
-.Kotlin
+[source,indent=0,subs="verbatim,quotes"]
 ----
 	bean(idOrNameOfBean)
 ----
@@ -515,7 +509,7 @@ of any public method.
 trading module.
 
 It is a best practice to build more complex pointcut expressions out of smaller named
-components, as shown earlier. When referring to pointcuts by name, normal Java visibility
+components, as shown above. When referring to pointcuts by name, normal Java visibility
 rules apply (you can see private pointcuts in the same type, protected pointcuts in the
 hierarchy, public pointcuts anywhere, and so on). Visibility does not affect pointcut
 matching.
@@ -526,8 +520,8 @@ matching.
 
 When working with enterprise applications, developers often want to refer to modules of
 the application and particular sets of operations from within several aspects. We
-recommend defining a `CommonPointcuts` aspect that captures common pointcut expressions
-for this purpose. Such an aspect typically resembles the following example:
+recommend defining a dedicated aspect that captures common pointcut expressions for this
+purpose. Such an aspect typically resembles the following `CommonPointcuts` example:
 
 [source,java,indent=0,subs="verbatim",role="primary",chomp="-packages"]
 .Java
@@ -659,9 +653,11 @@ for this purpose. Such an aspect typically resembles the following example:
 	}
 ----
 
-You can refer to the pointcuts defined in such an aspect anywhere you need a
-pointcut expression. For example, to make the service layer transactional, you could
-write the following:
+You can refer to the pointcuts defined in such an aspect anywhere you need a pointcut
+expression by referencing the fully-qualified class name of the aspect combined with the
+pointcut name. For example, to make the service layer transactional, you could write the
+following which references the shared `com.xyz.myapp.CommonPointcuts.businessService()`
+pointcut:
 
 [source,xml,indent=0,subs="verbatim,quotes"]
 ----
@@ -688,7 +684,7 @@ transaction elements are discussed in <<data-access.adoc#transaction, Transactio
 Spring AOP users are likely to use the `execution` pointcut designator the most often.
 The format of an execution expression follows:
 
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	execution(modifiers-pattern? ret-type-pattern declaring-type-pattern?name-pattern(param-pattern)
 				throws-pattern?)
@@ -714,42 +710,42 @@ The following examples show some common pointcut expressions:
 
 * The execution of any public method:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	execution(public * *(..))
 ----
 
 * The execution of any method with a name that begins with `set`:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	execution(* set*(..))
 ----
 
 * The execution of any method defined by the `AccountService` interface:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	execution(* com.xyz.service.AccountService.*(..))
 ----
 
 * The execution of any method defined in the `service` package:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	execution(* com.xyz.service.\*.*(..))
 ----
 
 * The execution of any method defined in the service package or one of its sub-packages:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	execution(* com.xyz.service..\*.*(..))
 ----
 
 * Any join point (method execution only in Spring AOP) within the service package:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	within(com.xyz.service.*)
 ----
@@ -757,7 +753,7 @@ The following examples show some common pointcut expressions:
 * Any join point (method execution only in Spring AOP) within the service package or one of its
 sub-packages:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	within(com.xyz.service..*)
 ----
@@ -765,7 +761,7 @@ sub-packages:
 * Any join point (method execution only in Spring AOP) where the proxy implements the
 `AccountService` interface:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	this(com.xyz.service.AccountService)
 ----
@@ -776,7 +772,7 @@ for how to make the proxy object available in the advice body.
 * Any join point (method execution only in Spring AOP) where the target object
 implements the `AccountService` interface:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	target(com.xyz.service.AccountService)
 ----
@@ -787,7 +783,7 @@ for how to make the target object available in the advice body.
 * Any join point (method execution only in Spring AOP) that takes a single parameter
 and where the argument passed at runtime is `Serializable`:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	args(java.io.Serializable)
 ----
@@ -803,7 +799,7 @@ parameter of type `Serializable`.
 * Any join point (method execution only in Spring AOP) where the target object has a
 `@Transactional` annotation:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	@target(org.springframework.transaction.annotation.Transactional)
 ----
@@ -814,7 +810,7 @@ how to make the annotation object available in the advice body.
 * Any join point (method execution only in Spring AOP) where the declared type of the
 target object has an `@Transactional` annotation:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	@within(org.springframework.transaction.annotation.Transactional)
 ----
@@ -825,7 +821,7 @@ how to make the annotation object available in the advice body.
 * Any join point (method execution only in Spring AOP) where the executing method has an
 `@Transactional` annotation:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	@annotation(org.springframework.transaction.annotation.Transactional)
 ----
@@ -836,7 +832,7 @@ for how to make the annotation object available in the advice body.
 * Any join point (method execution only in Spring AOP) which takes a single parameter,
 and where the runtime type of the argument passed has the `@Classified` annotation:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	@args(com.xyz.security.Classified)
 ----
@@ -847,7 +843,7 @@ how to make the annotation object(s) available in the advice body.
 * Any join point (method execution only in Spring AOP) on a Spring bean named
 `tradeService`:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	bean(tradeService)
 ----
@@ -855,7 +851,7 @@ how to make the annotation object(s) available in the advice body.
 * Any join point (method execution only in Spring AOP) on Spring beans having names that
 match the wildcard expression `*Service`:
 +
-[literal,subs="verbatim,quotes"]
+[literal,indent=0,subs="verbatim,quotes"]
 ----
 	bean(*Service)
 ----
@@ -877,7 +873,7 @@ about understanding the performance of various pointcut designators and may supp
 in any order in a pointcut declaration.
 
 However, AspectJ can work only with what it is told. For optimal performance of
-matching, you should think about what they are trying to achieve and narrow the search
+matching, you should think about what you are trying to achieve and narrow the search
 space for matches as much as possible in the definition. The existing designators
 naturally fall into one of three groups: kinded, scoping, and contextual:
 
@@ -943,8 +939,7 @@ You can declare before advice in an aspect by using the `@Before` annotation:
 	}
 ----
 
-If we use an in-place pointcut expression, we could rewrite the preceding example as the
-following example:
+If we use an in-place pointcut expression, we can rewrite the preceding example as follows:
 
 [source,java,indent=0,subs="verbatim",role="primary"]
 .Java