aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAlexander Kriegisch <Alexander@Kriegisch.name>2021-07-16 10:48:06 +0700
committerAlexander Kriegisch <Alexander@Kriegisch.name>2024-01-06 10:09:11 +0100
commita6a1dbea46fd4829189b23fb900da6a586a8151a (patch)
treeb6d8a3b4e38e320813566535c6ea4f036fb4ba91
parentfa63feda31a6a9656173a63dc057993d98469305 (diff)
downloadaspectj-a6a1dbea46fd4829189b23fb900da6a586a8151a.tar.gz
aspectj-a6a1dbea46fd4829189b23fb900da6a586a8151a.zip
Fix more AsciiDoc links and code blocks (WIP)
- Add Java syntax highlighting to AspectJ and Java files - Add XML syntax highlighting to XML files (Ant, LTW etc.) - Dedent and remove empty lines, where necessary - Enclose in-line line numbers for Java code in /*23*/ comments in order to enable Java formatting Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>
-rw-r--r--docs/adk15ProgGuideDB/annotations.adoc37
-rw-r--r--docs/adk15ProgGuideDB/ataspectj.adoc45
-rw-r--r--docs/adk15ProgGuideDB/autoboxing.adoc3
-rw-r--r--docs/adk15ProgGuideDB/covariance.adoc4
-rw-r--r--docs/adk15ProgGuideDB/enumeratedtypes.adoc1
-rw-r--r--docs/adk15ProgGuideDB/generics.adoc30
-rw-r--r--docs/adk15ProgGuideDB/grammar.adoc1
-rw-r--r--docs/adk15ProgGuideDB/joinpointsignatures.adoc11
-rw-r--r--docs/adk15ProgGuideDB/miscellaneous.adoc3
-rw-r--r--docs/adk15ProgGuideDB/pertypewithin.adoc4
-rw-r--r--docs/adk15ProgGuideDB/varargs.adoc8
-rw-r--r--docs/devGuideDB/aj.adoc1
-rw-r--r--docs/devGuideDB/ajbrowser.adoc2
-rw-r--r--docs/devGuideDB/ajc.adoc18
-rw-r--r--docs/devGuideDB/ajdb.adoc69
-rw-r--r--docs/devGuideDB/ajdee.adoc8
-rw-r--r--docs/devGuideDB/ajdoc.adoc1
-rw-r--r--docs/devGuideDB/antsupport.adoc16
-rw-r--r--docs/devGuideDB/aspectj-mode.adoc4
-rw-r--r--docs/devGuideDB/ltw.adoc11
-rw-r--r--docs/developer/amcDesignNotes.adoc3
-rw-r--r--docs/developer/compiler-weaver/index.adoc51
-rw-r--r--docs/dist/LICENSE-AspectJ.adoc1
-rw-r--r--docs/dist/doc/README-11.adoc446
-rw-r--r--docs/dist/doc/README-12.adoc201
-rw-r--r--docs/dist/doc/README-121.adoc23
-rw-r--r--docs/dist/doc/README-153.adoc11
-rw-r--r--docs/dist/doc/README-160.adoc19
-rw-r--r--docs/dist/doc/README-161.adoc9
-rw-r--r--docs/dist/doc/README-1610.adoc1
-rw-r--r--docs/dist/doc/README-1611.adoc2
-rw-r--r--docs/dist/doc/README-1612.adoc20
-rw-r--r--docs/dist/doc/README-164.adoc39
-rw-r--r--docs/dist/doc/README-167.adoc50
-rw-r--r--docs/dist/doc/README-168.adoc38
-rw-r--r--docs/dist/doc/README-169.adoc35
-rw-r--r--docs/dist/doc/README-170.adoc69
-rw-r--r--docs/dist/doc/README-174.adoc2
-rw-r--r--docs/dist/doc/README-180.adoc5
-rw-r--r--docs/dist/doc/README-182.adoc31
-rw-r--r--docs/dist/doc/README-183.adoc4
-rw-r--r--docs/dist/doc/README-187.adoc15
-rw-r--r--docs/dist/doc/README-190.adoc38
-rw-r--r--docs/dist/doc/README-191.adoc1
-rw-r--r--docs/dist/doc/README-193.adoc9
-rw-r--r--docs/dist/doc/README-195.adoc7
-rw-r--r--docs/dist/doc/README-196.adoc15
-rw-r--r--docs/dist/doc/changes.adoc6
-rw-r--r--docs/dist/doc/porting.adoc279
-rw-r--r--docs/faq/faq.adoc84
-rw-r--r--docs/pdGuideDB/ajcore.adoc2
-rw-r--r--docs/pdGuideDB/ltwdump.adoc3
-rw-r--r--docs/pdGuideDB/messages.adoc5
-rw-r--r--docs/pdGuideDB/trace.adoc3
-rw-r--r--docs/progGuideDB/examples.adoc131
-rw-r--r--docs/progGuideDB/gettingstarted.adoc42
-rw-r--r--docs/progGuideDB/idioms.adoc5
-rw-r--r--docs/progGuideDB/implementation.adoc6
-rw-r--r--docs/progGuideDB/language.adoc115
-rw-r--r--docs/progGuideDB/pitfalls.adoc5
-rw-r--r--docs/progGuideDB/quickreference.adoc314
-rw-r--r--docs/progGuideDB/semantics.adoc310
-rw-r--r--docs/sandbox/readme-sandbox.adoc6
-rw-r--r--docs/sandbox/trails/j2ee.adoc1
64 files changed, 1479 insertions, 1260 deletions
diff --git a/docs/adk15ProgGuideDB/annotations.adoc b/docs/adk15ProgGuideDB/annotations.adoc
index 795860a42..e0e56fc71 100644
--- a/docs/adk15ProgGuideDB/annotations.adoc
+++ b/docs/adk15ProgGuideDB/annotations.adoc
@@ -19,10 +19,10 @@ program source by using the `@` symbol. For example, the following piece
of code uses the `@Deprecated` annotation to indicate that the
`obsoleteMethod()` has been deprecated:
+[source, java]
....
@Deprecated
public void obsoleteMethod() { ... }
-
....
Annotations may be _marker annotations_, _single-valued annotations_, or
@@ -32,27 +32,27 @@ annotations, as in the deprecation example above. Single-value
annotation types have a single member, and the annotation may be written
in one of two equivalent forms:
+[source, java]
....
@SuppressWarnings({"unchecked"})
public void someMethod() {...}
-
....
or
+[source, java]
....
@SuppressWarnings(value={"unchecked"})
public void someMethod() {...}
-
....
Multi-value annotations must use the `member-name=value
` syntax to specify annotation values. For example:
+[source, java]
....
@Authenticated(role="supervisor",clearanceLevel=5)
public void someMethod() {...}
-
....
==== Retention Policies
@@ -96,6 +96,7 @@ presence or absence of annotations.
By default annotations are _not_ inherited. Given the following program
+[source, java]
....
@MyAnnotation
class Super {
@@ -105,7 +106,6 @@ class Super {
class Sub extends Super {
public void foo() {}
}
-
....
Then `Sub` _does not_ have the `MyAnnotation` annotation, and
@@ -133,6 +133,7 @@ permitted on pointcut declarations or on `declare` statements.
The following example illustrates the use of annotations in aspects:
+[source, java]
....
@AspectAnnotation
public abstract aspect ObserverProtocol {
@@ -192,6 +193,7 @@ advice statement by using the
the same way as the Java 5 SuppressWarnings annotation (See JLS
9.6.1.5), but has class file retention.
+[source, java]
....
import org.aspectj.lang.annotation.SuppressAjWarnings;
@@ -262,6 +264,7 @@ Some examples of annotation patterns follow:
AspectJ 1.5 extends type patterns to allow an optional
`AnnotationPattern` prefix.
+[source, text]
....
TypePattern := SimpleTypePattern |
'!' TypePattern |
@@ -288,9 +291,9 @@ pattern, the parenthesis are required (as in `(@Foo Hello+)`). In some
cases (such as a type pattern used within a `within` or `handler`
pointcut expression), the parenthesis are optional:
+[source, text]
....
OptionalParensTypePattern := AnnotationPattern? TypePattern
-
....
The following examples illustrate the use of annotations in type
@@ -330,6 +333,7 @@ patterns:
A `FieldPattern` can optionally specify an annotation-matching pattern
as the first element:
+[source, text]
....
FieldPattern :=
AnnotationPattern? FieldModifiersPattern?
@@ -371,6 +375,7 @@ annotations that match the pattern. For example:
A `MethodPattern` can optionally specify an annotation-matching pattern
as the first element.
+[source, text]
....
MethodPattern :=
AnnotationPattern? MethodModifiersPattern? TypePattern
@@ -397,6 +402,7 @@ TypePatternList := TypePattern (',' TypePattern)*
A `ConstructorPattern` has the form
+[source, text]
....
ConstructorPattern :=
AnnotationPattern? ConstructorModifiersPattern?
@@ -470,6 +476,7 @@ Like their counterparts, these pointcut designators can be used both for
join point matching, and to expose context. The format of these new
designators is:
+[source, text]
....
AtThis := '@this' '(' AnnotationOrIdentifer ')'
@@ -505,6 +512,7 @@ Annotations can be exposed as context in the body of advice by using the
forms of `@this(), @target()` and `@args()` that use bound variables in
the place of annotation names. For example:
+[source, java]
....
pointcut callToClassifiedObject(Classified classificationInfo) :
call(* *(..)) && @target(classificationInfo);
@@ -521,6 +529,7 @@ at a given position in an `@args` expression indicates that the runtime
type of the argument in that position at a join point must have an
annotation of the indicated type. For example:
+[source, java]
....
/**
* matches any join point with at least one argument, and where the
@@ -544,6 +553,7 @@ available reflectively with the body of advice through the
the arguments, or object bound to this or target at a join point you can
use the following code fragments:
+[source, java]
....
Annotation[] thisAnnotations = thisJoinPoint.getThis().getClass().getAnnotations();
Annotation[] targetAnnotations = thisJoinPoint.getTarget().getClass().getAnnotations();
@@ -555,6 +565,7 @@ point where the executing code is defined within a type (`@within`), or
a method/constructor (`@withincode`) that has an annotation of the
specified type. The form of these designators is:
+[source, text]
....
AtWithin := '@within' '(' AnnotationOrIdentifier ')'
AtWithinCode := '@withincode' '(' AnnotationOrIdentifier ')'
@@ -574,6 +585,7 @@ The `@annotation` pointcut designator matches any join point where the
_subject_ of the join point has an annotation of the given type. Like
the other @pcds, it can also be used for context exposure.
+[source, text]
....
AtAnnotation := '@annotation' '(' AnnotationOrIdentifier ')'
....
@@ -589,6 +601,7 @@ extended with additional operations that provide access to the
annnotations can be queried. The following fragment illustrates an
example use of this interface to access annotation information.
+[source, java]
....
Signature sig = thisJoinPointStaticPart.getSignature();
AnnotatedElement declaringTypeAnnotationInfo = sig.getDeclaringType();
@@ -621,6 +634,7 @@ considered to be an annotation on the parameter type or an annotation on
the parameter itself is determined through the use of parentheses around
the parameter type. Consider the following:
+[source, java]
....
@SomeAnnotation
class AnnotatedType {}
@@ -634,6 +648,7 @@ class C {
The method foo has a parameter of an annotated type, and can be matched
by this pointcut:
+[source, java]
....
pointcut p(): execution(* *(@SomeAnnotation *));
....
@@ -645,6 +660,7 @@ parameter of any type that has the annotation @SomeAnnotation'.
To match the parameter annotation case, the method goo, this is the
pointcut:
+[source, java]
....
pointcut p(): execution(* *(@SomeAnnotation (*)));
....
@@ -657,6 +673,7 @@ annotation of @SomeAnnotation'.
To match when there is a parameter annotation and an annotation on the
type as well:
+[source, java]
....
pointcut p(): execution(* *(@SomeAnnotation (@SomeOtherAnnotation *)));
....
@@ -671,6 +688,7 @@ According to the Java 5 specification, non-type annotations are not
inherited, and annotations on types are only inherited if they have the
`@Inherited` meta-annotation. Given the following program:
+[source, java]
....
class C1 {
@SomeAnnotation
@@ -714,6 +732,7 @@ actually being called).
The `if` pointcut designator can be used to write pointcuts that match
based on the values annotation members. For example:
+[source, java]
....
pointcut txRequiredMethod(Tx transactionAnnotation) :
execution(* *(..)) && @this(transactionAnnotation)
@@ -729,12 +748,14 @@ Since pointcut expressions in AspectJ 5 support join point matching
based on annotations, this facility can be exploited when writing
`declare warning` and `declare error` statements. For example:
+[source, java]
....
declare warning : withincode(@PerformanceCritical * *(..)) &&
call(@ExpensiveOperation * *(..))
: "Expensive operation called from within performance critical section";
....
+[source, java]
....
declare error : call(* org.xyz.model.*.*(..)) &&
!@within(Trusted)
@@ -745,6 +766,7 @@ declare error : call(* org.xyz.model.*.*(..)) &&
The general form of a `declare parents` statement is:
+[source, text]
....
declare parents : TypePattern extends Type;
declare parents : TypePattern implements TypeList;
@@ -774,6 +796,7 @@ issued).
The general form of a declare precedence statement is:
+[source, java]
....
declare precedence : TypePatList;
....
@@ -798,6 +821,7 @@ a future release.
The general form is:
+[source, text]
....
declare @<kind> : ElementPattern : Annotation ;
....
@@ -809,6 +833,7 @@ specified by the `@Target` annotation.
`ElementPattern` is defined as follows:
+[source, text]
....
ElementPattern := TypePattern |
MethodPattern |
diff --git a/docs/adk15ProgGuideDB/ataspectj.adoc b/docs/adk15ProgGuideDB/ataspectj.adoc
index e69fb205a..7f480f667 100644
--- a/docs/adk15ProgGuideDB/ataspectj.adoc
+++ b/docs/adk15ProgGuideDB/ataspectj.adoc
@@ -30,6 +30,7 @@ used to declare aspects and aspect members.
Aspect declarations are supported by the
`org.aspectj.lang.annotation.Aspect` annotation. The declaration:
+[source, java]
....
@Aspect
public class Foo {}
@@ -37,6 +38,7 @@ public class Foo {}
Is equivalent to:
+[source, java]
....
public aspect Foo {}
....
@@ -44,6 +46,7 @@ public aspect Foo {}
To specify an aspect an aspect instantiation model (the default is
singleton), provide the perclause as the `@Aspect` value. For example:
+[source, java]
....
@Aspect("perthis(execution(* abc..*(..)))")
public class Foo {}
@@ -51,6 +54,7 @@ public class Foo {}
is equivalent to...
+[source, java]
....
public aspect Foo perthis(execution(* abc..*(..))) {}
....
@@ -86,6 +90,7 @@ section.
Here is a simple example of a pointcut declaration in both code and
@AspectJ styles:
+[source, java]
....
@Pointcut("call(* *.*(..))")
void anyCall() {}
@@ -93,6 +98,7 @@ void anyCall() {}
is equivalent to...
+[source, java]
....
pointcut anyCall() : call(* *.*(..));
....
@@ -100,6 +106,7 @@ pointcut anyCall() : call(* *.*(..));
When binding arguments, simply declare the arguments as normal in the
annotated method:
+[source, java]
....
@Pointcut("call(* *.*(int)) && args(i) && target(callee)")
void anyCall(int i, Foo callee) {}
@@ -107,6 +114,7 @@ void anyCall(int i, Foo callee) {}
is equivalent to...
+[source, java]
....
pointcut anyCall(int i, Foo callee) : call(* *.*(int)) && args(i) && target(callee);
....
@@ -115,6 +123,7 @@ An example with modifiers (Remember that Java 5 annotations are not
inherited, so the `@Pointcut` annotation must be present on the
extending aspect's pointcut declaration too):
+[source, java]
....
@Pointcut("")
protected abstract void anyCall();
@@ -122,6 +131,7 @@ protected abstract void anyCall();
is equivalent to...
+[source, java]
....
protected abstract pointcut anyCall();
....
@@ -139,6 +149,7 @@ scope.
Consider the following compilation unit:
+[source, java]
....
package org.aspectprogrammer.examples;
@@ -152,6 +163,7 @@ public aspect Foo {
Using the annotation style this would be written as:
+[source, java]
....
package org.aspectprogrammer.examples;
@@ -186,6 +198,7 @@ have either an empty body (`if()`, or be one of the expression forms
and return a boolean. The body of the method contains the condition to
be evaluated. For example:
+[source, java]
....
@Pointcut("call(* *.*(int)) && args(i) && if()")
public static boolean someCallWithIfTest(int i) {
@@ -195,12 +208,14 @@ public static boolean someCallWithIfTest(int i) {
is equivalent to...
+[source, java]
....
pointcut someCallWithIfTest(int i) : call(* *.*(int)) && args(i) && if(i > 0);
....
and the following is also a valid form:
+[source, java]
....
static int COUNT = 0;
@@ -260,6 +275,7 @@ method execution join point).
The following example shows a simple before advice declaration in both
styles:
+[source, java]
....
@Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
public void callFromFoo() {
@@ -269,6 +285,7 @@ public void callFromFoo() {
is equivalent to...
+[source, java]
....
before() : call(* org.aspectprogrammer..*(..)) && this(Foo) {
System.out.println("Call from Foo");
@@ -278,6 +295,7 @@ before() : call(* org.aspectprogrammer..*(..)) && this(Foo) {
If the advice body needs to know which particular `Foo` instance is
making the call, just add a parameter to the advice declaration.
+[source, java]
....
before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
System.out.println("Call from Foo: " + foo);
@@ -286,6 +304,7 @@ before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
can be written as:
+[source, java]
....
@Before("call(* org.aspectprogrammer..*(..)) && this(foo)")
public void callFromFoo(Foo foo) {
@@ -298,6 +317,7 @@ If the advice body needs access to `thisJoinPoint` ,
these need to be declared as additional method parameters when using the
annotation style.
+[source, java]
....
@Before("call(* org.aspectprogrammer..*(..)) && this(foo)")
public void callFromFoo(JoinPoint thisJoinPoint, Foo foo) {
@@ -308,6 +328,7 @@ public void callFromFoo(JoinPoint thisJoinPoint, Foo foo) {
is equivalent to...
+[source, java]
....
before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
System.out.println("Call from Foo: " + foo + " at "
@@ -317,6 +338,7 @@ before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
Advice that needs all three variables would be declared:
+[source, java]
....
@Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
public void callFromFoo(JoinPoint thisJoinPoint,
@@ -340,6 +362,7 @@ To expose a return value with after returning advice simply declare the
returning parameter as a parameter in the method body and bind it with
the "returning" attribute:
+[source, java]
....
@AfterReturning("criticalOperation()")
public void phew() {
@@ -354,6 +377,7 @@ public void itsAFoo(Foo f) {
is equivalent to...
+[source, java]
....
after() returning : criticalOperation() {
System.out.println("phew");
@@ -375,6 +399,7 @@ the design goals for the annotation style is that a large class of
AspectJ applications should be compilable with a standard Java 5
compiler. A straight call to `proceed` inside a method body:
+[source, java]
....
@Around("call(* org.aspectprogrammer..*(..))")
public Object doNothing() {
@@ -386,6 +411,7 @@ will result in a "No such method" compilation error. For this reason
AspectJ 5 defines a new sub-interface of `JoinPoint` ,
`ProceedingJoinPoint` .
+[source, java]
....
public interface ProceedingJoinPoint extends JoinPoint {
public Object proceed(Object[] args);
@@ -394,6 +420,7 @@ public interface ProceedingJoinPoint extends JoinPoint {
The around advice given above can now be written as:
+[source, java]
....
@Around("call(* org.aspectprogrammer..*(..))")
public Object doNothing(ProceedingJoinPoint thisJoinPoint) {
@@ -403,6 +430,7 @@ public Object doNothing(ProceedingJoinPoint thisJoinPoint) {
Here's an example that uses parameters for the proceed call:
+[source, java]
....
@Aspect
public class ProceedAspect {
@@ -420,6 +448,7 @@ public class ProceedAspect {
is equivalent to:
+[source, java]
....
public aspect ProceedAspect {
pointcut setAge(int i): call(* setAge(..)) && args(i);
@@ -505,6 +534,7 @@ introduce a marker interface.
Consider the following aspect:
+[source, java]
....
public aspect MoodIndicator {
@@ -532,6 +562,7 @@ type of the inter-type declaration).
Using the annotation style this aspect can be written:
+[source, java]
....
@Aspect
public class MoodIndicator {
@@ -575,6 +606,7 @@ aspect' field of a non-interface type. The interface type is the
inter-type declaration contract that dictates which methods are declared
on the target type.
+[source, java]
....
// this type will be affected by the inter-type declaration as the type pattern matches
package org.xyz;
@@ -596,6 +628,7 @@ interface methods.
Consider the following aspect:
+[source, java]
....
public aspect SerializableMarker {
declare parents : org.xyz..* implements Serializable;
@@ -604,6 +637,7 @@ public aspect SerializableMarker {
Using the annotation style this aspect can be written:
+[source, java]
....
@Aspect
public class SerializableMarker {
@@ -620,6 +654,7 @@ implemented by the target type, an error will be issued during weaving.
Consider the following aspect:
+[source, java]
....
public aspect MoodIndicator {
@@ -647,6 +682,7 @@ type of the inter-type declaration).
Using the annotation style this aspect can be written:
+[source, java]
....
@Aspect
public class MoodIndicator {
@@ -690,6 +726,7 @@ Exploiting this syntax requires the user to obey the rules of pure Java.
So references to any targeted type as if it were affected by the Mixin
must be made through a cast, like this:
+[source, java]
....
// this type will be affected by the inter-type declaration as the type pattern matches
package org.xyz;
@@ -710,6 +747,7 @@ parameter. If it does, then when the factory method is called the
parameter will be the object instance for which a delegate should be
created:
+[source, java]
....
@Aspect
public class Foo {
@@ -725,6 +763,7 @@ It is also possible to make the factory method non-static - and in this
case it can then exploit the local state in the surrounding aspect
instance, but this is only supported for singleton aspects:
+[source, java]
....
@Aspect
public class Foo {
@@ -743,6 +782,7 @@ necessary. In this example the return type of the method extends
multiple other interfaces and only a couple of them (I and J) should be
mixed into any matching targets:
+[source, java]
....
// interfaces is an array of interface classes that should be mixed in
@DeclareMixin(value="org.xyz..*",interfaces={I.class,J.class})
@@ -777,6 +817,7 @@ Declare annotation is also not supported in the 1.5.0 release of AspectJ
Declare precedence _is_ supported. For declare precedence, use the
`@DeclarePrecedence` annotation as in the following example:
+[source, java]
....
public aspect SystemArchitecture {
declare precedence : Security*, TransactionSupport, Persistence;
@@ -787,6 +828,7 @@ public aspect SystemArchitecture {
can be written as:
+[source, java]
....
@Aspect
@DeclarePrecedence("Security*,org.xyz.TransactionSupport,org.xyz.Persistence")
@@ -806,6 +848,7 @@ issued.
Note that the String must be a literal and not the result of the
invocation of a static method for example.
+[source, java]
....
declare warning : call(* javax.sql..*(..)) && !within(org.xyz.daos..*)
: "Only DAOs should be calling JDBC.";
@@ -816,6 +859,7 @@ declare error : execution(* IFoo+.*(..)) && !within(org.foo..*)
can be written as...
+[source, java]
....
@DeclareWarning("call(* javax.sql..*(..)) && !within(org.xyz.daos..*)")
static final String aMessage = "Only DAOs should be calling JDBC.";
@@ -844,6 +888,7 @@ compilation error if another part of the program tries to call them.
To provide equivalent support for AspectJ applications compiled with a
standard Java 5 compiler, AspectJ 5 defines the `Aspects` utility class:
+[source, java]
....
public class Aspects {
diff --git a/docs/adk15ProgGuideDB/autoboxing.adoc b/docs/adk15ProgGuideDB/autoboxing.adoc
index ced4f49fe..8426ea45f 100644
--- a/docs/adk15ProgGuideDB/autoboxing.adoc
+++ b/docs/adk15ProgGuideDB/autoboxing.adoc
@@ -15,6 +15,7 @@ assignments or method or constructor invocations.
For example:
+[source, java]
....
int i = 0;
i = new Integer(5); // auto-unboxing
@@ -28,6 +29,7 @@ Integer i2 = 5; // autoboxing
Most of the pointcut designators match based on signatures, and hence
are unaffected by autoboxing. For example, a call to a method
+[source, java]
....
public void foo(Integer i);
....
@@ -52,6 +54,7 @@ single argument of type `Integer` or of type `int`.
Autoboxing and unboxing are also applied when binding pointcut or advice
parameters, for example:
+[source, java]
....
pointcut foo(int i) : args(i);
diff --git a/docs/adk15ProgGuideDB/covariance.adoc b/docs/adk15ProgGuideDB/covariance.adoc
index fa1a2ddcc..49dda35ee 100644
--- a/docs/adk15ProgGuideDB/covariance.adoc
+++ b/docs/adk15ProgGuideDB/covariance.adoc
@@ -6,6 +6,7 @@
Java 5 (and hence AspectJ 5) allows you to narrow the return type in an
overriding method. For example:
+[source, java]
....
class A {
public A whoAreYou() {...}
@@ -26,6 +27,7 @@ designators are extended to match against covariant methods.
Given the classes `A` and `B` as defined in the previous section, and
the program fragment
+[source, java]
....
A a = new A();
B b = new B();
@@ -35,12 +37,14 @@ b.whoAreYou();
The signatures for the call join point `a.whoAreYou()` are simply:
+[source, java]
....
A A.whoAreYou()
....
The signatures for the call join point `b.whoAreYou()` are:
+[source, java]
....
A A.whoAreYou()
B B.whoAreYou()
diff --git a/docs/adk15ProgGuideDB/enumeratedtypes.adoc b/docs/adk15ProgGuideDB/enumeratedtypes.adoc
index 6124a5e55..1149d06f3 100644
--- a/docs/adk15ProgGuideDB/enumeratedtypes.adoc
+++ b/docs/adk15ProgGuideDB/enumeratedtypes.adoc
@@ -8,6 +8,7 @@ Java 5 (and hence AspectJ 5) provides explicit support for enumerated
types. In the simplest case, you can declare an enumerated type as
follows:
+[source, java]
....
public enum ProgrammingLanguages {
COBOL, C, JAVA, ASPECTJ
diff --git a/docs/adk15ProgGuideDB/generics.adoc b/docs/adk15ProgGuideDB/generics.adoc
index 3a00cfc52..cd9c101b1 100644
--- a/docs/adk15ProgGuideDB/generics.adoc
+++ b/docs/adk15ProgGuideDB/generics.adoc
@@ -15,6 +15,7 @@ the type name. By convention formal type parameters are named using a
single letter, though this is not required. A simple generic list type
(that can contain elements of any type `E`) could be declared:
+[source, java]
....
interface List<E> {
Iterator<E> iterator();
@@ -63,6 +64,7 @@ parameterized type by specifying a concrete type specfication for each
type parameter in the generic type. The following example declares a
list of strings and a list of numbers:
+[source, java]
....
List<String> strings;
List<Number> numbers;
@@ -78,6 +80,7 @@ written in the Java 5 language would not be expected to use raw types.
Parameterized types are instantiated by specifying type parameter values
in the constructor call expression as in the following examples:
+[source, java]
....
List<String> strings = new MyListImpl<String>();
List<Number> numbers = new MyListImpl<Number>();
@@ -135,6 +138,7 @@ The supertype of a generic type `C` is the type given in the extends
clause of `C`, or `Object` if no extends clause is present. Given the
type declaration
+[source, java]
....
public interface List<E> extends Collection<E> {... }
....
@@ -164,6 +168,7 @@ type `List<? extends Number>`.
A static method may be declared with one or more type parameters as in
the following declaration:
+[source, java]
....
static <T> T first(List<T> ts) { ... }
....
@@ -174,6 +179,7 @@ not need to be declared as a type parameter of the enclosing type.
Non-static methods may also be declared with one or more type parameters
in a similar fashion:
+[source, java]
....
<T extends Number> T max(T t1, T t2) { ... }
....
@@ -215,6 +221,7 @@ generic type.
Generic methods and constructors, and members defined in generic types,
may use type variables as part of their signature. For example:
+[source, java]
....
public class Utils {
@@ -334,6 +341,7 @@ types (methods) and field types (fields). This is achieved by specifying
a parameterized type pattern at the appropriate point in the signature
pattern. For example, given the class `Foo`:
+[source, java]
....
public class Foo {
@@ -376,6 +384,7 @@ expression `call(* addStrings(List))` and by the expression
Remember that any type variable reference in a generic member is
_always_ matched by its erasure. Thus given the following example:
+[source, java]
....
class G<T> {
List<T> foo(List<String> ls) { return null; }
@@ -396,6 +405,7 @@ different type to `List<String>`, even though a variable of type
`List<String>` can be assigned to a variable of type `List<?>`. Given
the methods:
+[source, java]
....
class C {
public void foo(List<? extends Number> listOfSomeNumberType) {}
@@ -423,6 +433,7 @@ Under certain circumstances a Java 5 compiler is required to create
_bridge methods_ that support the compilation of programs using raw
types. Consider the types
+[source, java]
....
class Generic<T> {
public T foo(T someObject) {
@@ -445,6 +456,7 @@ in `Generic`. This is an example of a case where a Java 5 compiler will
create a _bridge method_ in `SubGeneric`. Although you never see it, the
bridge method will look something like this:
+[source, java]
....
public Object foo(Object arg) {
Number n = (Number) arg; // "bridge" to the signature defined in this type
@@ -464,6 +476,7 @@ It _is_ possible to _call_ a bridge method as the following short code
snippet demonstrates. Such a call _does_ result in a call join point for
the call to the method.
+[source, java]
....
SubGeneric rawType = new SubGeneric();
rawType.foo("hi"); // call to bridge method (will result in a runtime failure in this case)
@@ -483,6 +496,7 @@ types with the `this()` and `target()` pointcuts. Parameterized types
may however be used in conjunction with `args()`. Consider the following
class
+[source, java]
....
public class C {
public void foo(List<String> listOfStrings) {}
@@ -513,6 +527,7 @@ args(List<Double>)::
instance of List at join point method-execution(void C.goo(List<?
extends Number>)) [Xlint:uncheckedArgument]";
+[source, java]
....
public aspect A {
before(List<Double> listOfDoubles) : execution(* C.*(..)) && args(listOfDoubles) {
@@ -533,6 +548,7 @@ pointcut associated with the advice will be suppressed. To suppress just
an `uncheckedArgument` warning, use the annotation
`@SuppressWarnings("uncheckedArgument")` as in the following examples:
+[source, java]
....
import org.aspectj.lang.annotation.SuppressAjWarnings
public aspect A {
@@ -560,6 +576,7 @@ following example the advice will match the execution of `bar` but not
of `goo` since the signature of `goo` is not matched by the execution
pointcut expression.
+[source, java]
....
public aspect A {
before(List<Double> listOfDoubles) : execution(* C.*(List<Double>)) && args(listOfDoubles) {
@@ -580,6 +597,7 @@ an `uncheckedArgument` warning.
Consider the following program:
+[source, java]
....
public class C {
public static void main(String[] args) {
@@ -622,6 +640,7 @@ to a method declared to take a `List<? extends Number>`,
matching to only those join points at which the argument is guaranteed
to be an instance of `List<? extends Number>`.
+[source, java]
....
aspect A {
before(List<? extends Number> aListOfSomeNumberType)
@@ -641,6 +660,7 @@ described for args. For example, the following aspect matches the
execution of any method returning a `List`, and makes the returned list
available to the body of the advice.
+[source, java]
....
public aspect A {
pointcut executionOfAnyMethodReturningAList() : execution(List *(..));
@@ -661,6 +681,7 @@ we only perform safe operations on the list.
Given the class
+[source, java]
....
public class C {
public List<String> foo(List<String> listOfStrings) {...}
@@ -676,6 +697,7 @@ bind the return value. It will also run after the execution of `goo` and
bind the return value, but gives an `uncheckedArgument` warning during
compilation. It does _not_ run after the execution of `foo`.
+[source, java]
....
public aspect Returning {
after() returning(List<Double> listOfDoubles) : execution(* C.*(..)) {
@@ -701,6 +723,7 @@ reference, and not a raw type reference.
Consider the generic type `Generic` with a pointcut `foo`:
+[source, java]
....
public class Generic<T> {
/**
@@ -713,6 +736,7 @@ public class Generic<T> {
Such a pointcut must be refered to using a parameterized reference as
shown below.
+[source, java]
....
public aspect A {
// runs before the execution of any implementation of a method defined for MyClass
@@ -813,6 +837,7 @@ permitted in this parameterization.
Given the aspect declaration:
+[source, java]
....
public abstract aspect ParentChildRelationship<P,C> {
...
@@ -843,6 +868,7 @@ within inter-type declarations_. For example, we can declare a
`ParentChildRelationship` aspect to manage the bi-directional
relationship between parent and child nodes as follows:
+[source, java]
....
/**
* a generic aspect, we've used descriptive role names for the type variables
@@ -939,6 +965,7 @@ parent and child. In a compiler implementation managing an abstract
syntax tree (AST) in which AST nodes may contain other AST nodes we
could declare the concrete aspect:
+[source, java]
....
public aspect ASTNodeContainment extends ParentChildRelationship<ASTNode,ASTNode> {
before(ASTNode parent, ASTNode child) : addingChild(parent, child) {
@@ -965,6 +992,7 @@ void setParent(ASTNode parent)
In a system managing orders, we could declare the concrete aspect:
+[source, java]
....
public aspect OrderItemsInOrders extends ParentChildRelationship<Order, OrderItem> {
}
@@ -991,6 +1019,7 @@ void setParent(Order parent)
A second example of an abstract aspect, this time for handling
exceptions in a uniform manner, is shown below:
+[source, java]
....
abstract aspect ExceptionHandling<T extends Throwable> {
@@ -1024,6 +1053,7 @@ of the aspect to be designed to work together in a type-safe manner. The
following concrete sub-aspect shows how the abstract aspect might be
extended to handle `IOExceptions`.
+[source, java]
....
public aspect IOExceptionHandling extends ExceptionHandling<IOException>{
diff --git a/docs/adk15ProgGuideDB/grammar.adoc b/docs/adk15ProgGuideDB/grammar.adoc
index df4b33af8..3e1f345e5 100644
--- a/docs/adk15ProgGuideDB/grammar.adoc
+++ b/docs/adk15ProgGuideDB/grammar.adoc
@@ -1,6 +1,7 @@
[[grammar]]
== A Grammar for the AspectJ 5 Language
+[source, text]
....
=== type patterns ===
diff --git a/docs/adk15ProgGuideDB/joinpointsignatures.adoc b/docs/adk15ProgGuideDB/joinpointsignatures.adoc
index d8bf63c4d..07df75f92 100644
--- a/docs/adk15ProgGuideDB/joinpointsignatures.adoc
+++ b/docs/adk15ProgGuideDB/joinpointsignatures.adoc
@@ -25,6 +25,7 @@ A kinded pointcut is written using patterns, some of which match based
on _signature_, and some of which match based on _modifiers_. For
example, in the `call` pointcut designator:
+[source, text]
....
call(ModifierPattern TypePattern TypePattern.IdPattern(TypePatternList) ThrowsPattern)
....
@@ -96,6 +97,7 @@ For a call join point where a call is made to a method
`m(parameter_types)` on a target type `T` (where `T` is the static type
of the target):
+[source, java]
....
T t = new T();
t.m("hello"); <= call join point occurs when this line is executed
@@ -108,6 +110,7 @@ declare a definition of `m(parameter_types)`, then `R(T)` is the return
type in the definition of `m` that `T` inherits. Given the call above,
and the definition of `T.m`:
+[source, java]
....
interface Q {
R m(String s);
@@ -135,6 +138,7 @@ signature of the call join point, where `R(A)` is the return type of `
Continuing the example from above,we can deduce that
+[source, java]
....
R' S.m(String)
R P.m(String)
@@ -151,6 +155,7 @@ different declaring type.
Join point signatures for execution join points are defined in a similar
manner to signatures for call join points. Given the hierarchy:
+[source, java]
....
interface Q {
R m(String s);
@@ -174,6 +179,7 @@ class U extends T {
Then the execution join point signatures arising as a result of the call
to `u.m("hello")` are:
+[source, java]
....
R' U.m(String)
R' S.m(String)
@@ -198,6 +204,7 @@ If `T` does not directly declare a member `f`, then for each super type
does declare the member `f`, `F S.f` is a signature of the join point.
For example, given the hierarchy:
+[source, java]
....
class P {
F f;
@@ -213,6 +220,7 @@ class T extends S { }
Then the join point signatures for a field get join point of the field
`f` on an object with declared type `T` are:
+[source, java]
....
F S.f
F T.f
@@ -263,6 +271,7 @@ chain.
For example, given the following types
+[source, java]
....
public class X {
@Foo
@@ -293,6 +302,7 @@ point
Given the hierarchy
+[source, java]
....
interface Q {
R m(String s);
@@ -313,6 +323,7 @@ class T extends S {}
and the program fragment:
+[source, java]
....
P p = new P();
S s = new S();
diff --git a/docs/adk15ProgGuideDB/miscellaneous.adoc b/docs/adk15ProgGuideDB/miscellaneous.adoc
index 68c99d2ad..0043c965b 100644
--- a/docs/adk15ProgGuideDB/miscellaneous.adoc
+++ b/docs/adk15ProgGuideDB/miscellaneous.adoc
@@ -8,6 +8,7 @@ AspectJ 5 is more liberal than AspectJ 1.2.1 in accepting pointcut
expressions that bind context variables in more than one location. For
example, AspectJ 1.2.1 does not allow:
+[source, java]
....
pointcut foo(Foo foo) : (execution(* *(..)) && this(foo) ) ||
(set(* *) && target(foo));
@@ -28,6 +29,7 @@ exceptions. If the exception type specified in a declare soft statement
is `RuntimeException` or a subtype of `RuntimeException` then a new
XLint warning will be issued:
+[source, java]
....
declare soft : SomeRuntimeException : execution(* *(..));
@@ -43,6 +45,7 @@ _checked_ exception thrown at a matched join point, where the exception
is an instance of the softened exception, will be softened to an
`org.aspectj.lang.SoftException`.
+[source, java]
....
public aspect SoftenExample {
declare soft : Exception : execution(* Foo.*(..));
diff --git a/docs/adk15ProgGuideDB/pertypewithin.adoc b/docs/adk15ProgGuideDB/pertypewithin.adoc
index db2df9252..6d7b12a0e 100644
--- a/docs/adk15ProgGuideDB/pertypewithin.adoc
+++ b/docs/adk15ProgGuideDB/pertypewithin.adoc
@@ -5,6 +5,7 @@ AspectJ 5 defines a new per-clause type for aspect instantiation:
`pertypewithin`. Unlike the other per-clauses, `pertypewithin` takes a
type pattern:
+[source, text]
....
PerTypeWithin := 'pertypewithin' '(' OptionalParensTypePattern ')'
....
@@ -16,6 +17,7 @@ the associated type pattern.
Pertypewithin aspects have `aspectOf` and `hasAspect` methods with the
following signatures:
+[source, java]
....
/**
* return true if this aspect has an instance associated with
@@ -37,6 +39,7 @@ In addition, `pertypewithin` aspects have a `getWithinTypeName` method
that can be called to return the package qualified name of the type for
which the aspect instance has been created.
+[source, java]
....
/**
* return the package qualified name (eg. com.foo.MyClass) of the type
@@ -51,6 +54,7 @@ upon an implicit pointcut condition. In this case, that any join point
be `within` the type that the executing aspect is an `aspectOf`. For
example, given the aspect definition
+[source, java]
....
import java.util.*;
diff --git a/docs/adk15ProgGuideDB/varargs.adoc b/docs/adk15ProgGuideDB/varargs.adoc
index fe1500c1f..bf644ace3 100644
--- a/docs/adk15ProgGuideDB/varargs.adoc
+++ b/docs/adk15ProgGuideDB/varargs.adoc
@@ -7,6 +7,7 @@ Java 5 (and hence AspectJ 5) allows you to specify methods that take a
variable number of arguments of a specified type. This is achieved using
an ellipsis (...) in the method signature as shown:
+[source, java]
....
public void foo(int i, String... strings) {
}
@@ -21,6 +22,7 @@ A _varargs_ method may be called with zero or more arguments in the
variable argument position. For example, given the definition of `foo`
above, the following calls are all legal:
+[source, java]
....
foo(5);
foo(5,"One String");
@@ -31,6 +33,7 @@ foo(3,"One String","Two Strings","Three Strings");
A _varargs_ parameter is treated as an array within the defining member.
So in the body of `foo` we could write for example:
+[source, java]
....
public void foo(int i, String... strings) {
String[] someStrings = strings;
@@ -41,6 +44,7 @@ public void foo(int i, String... strings) {
One consequence of this treatment of a varargs parameter as an array is
that you can also call a varargs method with an array:
+[source, java]
....
foo(7,new String[] {"One String","Two Strings"});
....
@@ -63,6 +67,7 @@ annotations (xref:annotations.adoc#signaturePatterns[Signature Patterns]), that
`ConstructorPattern` are extended to allow a `varargs` pattern in the
last argument position of a method or constructor signature.
+[source, text]
....
FormalsPattern := '..' (',' FormalsPatternAfterDotDot)? |
OptionalParensTypePattern (',' FormalsPattern)* |
@@ -93,6 +98,7 @@ initialization(org.xyz.*.new((Foo || Goo)...))::
A variable argument parameter and an array parameter are treated as
distinct signature elements, so given the method definitions:
+[source, java]
....
void foo(String...);
void bar(String[]);
@@ -110,6 +116,7 @@ array type, as discussed in the introduction to this section. We follow
the same convention when binding a varargs parameter via the `args`
pointcut designator. Given a method
+[source, java]
....
public void foo(int i, String... strings) {
}
@@ -123,6 +130,7 @@ syntax within an args pointcut designator - so you _cannot_ write
Binding of a varargs parameter in an advice statement is
straightforward:
+[source, java]
....
before(int i, String[] ss) : call(* foo(int,String...)) && args(i,ss) {
// varargs String... argument is accessible in advice body through ss
diff --git a/docs/devGuideDB/aj.adoc b/docs/devGuideDB/aj.adoc
index 28b50e976..0a7b53108 100644
--- a/docs/devGuideDB/aj.adoc
+++ b/docs/devGuideDB/aj.adoc
@@ -27,6 +27,7 @@ xref:ltw.adoc#ltw[Load-Time Weaving].
Use ajc to build a library, then weave at load time
+[source, text]
....
REM compile library
${ASPECTJ_HOME}\bin\ajc.bat -outjar lib\aspects.jar @aspects.lst
diff --git a/docs/devGuideDB/ajbrowser.adoc b/docs/devGuideDB/ajbrowser.adoc
index 26c762e57..b092ebad5 100644
--- a/docs/devGuideDB/ajbrowser.adoc
+++ b/docs/devGuideDB/ajbrowser.adoc
@@ -17,9 +17,9 @@ invoke the script in `{aspectj}/bin` (if AspectJ is installed correctly)
or by using the `aspectjtools.jar` directly, and specifying no arguments
or some number of build configuration files (suffix `.lst`):
+[source, text]
....
java -jar aspectj1.1/lib/aspectjtools.jar aspectj1.1/doc/examples/spacewar/debug.lst
-
....
[[ajbrowser-building]]
diff --git a/docs/devGuideDB/ajc.adoc b/docs/devGuideDB/ajc.adoc
index 02d49b788..fcbc8f492 100644
--- a/docs/devGuideDB/ajc.adoc
+++ b/docs/devGuideDB/ajc.adoc
@@ -146,6 +146,7 @@ destination directory on the inpath and rebuild.)
Emit warnings for any instances of the comma-delimited list of
questionable code (eg '-warn:unusedLocals,deprecation'):
+
+[source, text]
....
constructorName method with constructor name
packageDefaultMethod attempt to override package-default method
@@ -168,6 +169,7 @@ none suppress all compiler warnings
-g<:[lines,vars,source]>::
debug attributes level, that may take three forms:
+
+[source, text]
....
-g all debug info ('-g:lines,vars,source')
-g:none no debug info
@@ -261,6 +263,7 @@ previous releases of AspectJ, see xref:compatibility.adoc#versionCompatibility[V
Compile two files:
+[source, text]
....
ajc HelloWorld.java Trace.java
....
@@ -271,6 +274,7 @@ relative to the argfile, and may include other argfiles by @-reference.
The following file `sources.lst` contains absolute and relative files
and @-references:
+[source, text]
....
Gui.java
/home/user/src/Library.java
@@ -283,6 +287,7 @@ view/body/ArrayView.java
Compile the files using either the -argfile or @ form:
+[source, text]
....
ajc -argfile sources.lst
ajc @sources.lst
@@ -317,6 +322,7 @@ sources with the aspect library.
The tracing example is in the AspectJ distribution
(\{aspectj}/doc/examples/tracing). This uses the following files:
+[source, text]
....
aspectj1.1/
bin/
@@ -346,6 +352,7 @@ environment as needed.
Setup the path, classpath, and current directory:
+[source, text]
....
cd examples
export ajrt=../lib/aspectjrt.jar
@@ -355,18 +362,21 @@ export PATH="../bin:$PATH"
Build a read-only tracing library:
+[source, text]
....
ajc -argfile tracing/tracelib.lst -outjar tracelib.jar
....
Build the application with tracing in one step:
+[source, text]
....
ajc -aspectpath tracelib.jar -argfile tracing/notrace.lst -outjar tracedapp.jar
....
Run the application with tracing:
+[source, text]
....
java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain
....
@@ -376,6 +386,7 @@ Build the application with tracing from binaries in two steps:
* (a) Build the application classes (using javac for
demonstration's sake):
+
+[source, text]
....
mkdir classes
javac -d classes tracing/*.java
@@ -383,18 +394,21 @@ jar cfM app.jar -C classes .
....
* (b) Build the application with tracing:
+
+[source, text]
....
ajc -inpath app.jar -aspectpath tracelib.jar -outjar tracedapp.jar
....
Run the application with tracing (same as above):
+[source, text]
....
java -classpath "$ajrt;tracedapp.jar;tracelib.jar" tracing.ExampleMain
....
Run the application without tracing:
+[source, text]
....
java -classpath "app.jar" tracing.ExampleMain
....
@@ -418,6 +432,7 @@ to collect the messages, use `MessageHandler` as your `IMessageHolder`.
For example, compile and run the following with `aspectjtools.jar` on
the classpath:
+[source, java]
....
import org.aspectj.bridge.*;
import org.aspectj.tools.ajc.Main;
@@ -454,6 +469,7 @@ the -XnoInline option.)
Probably the only time you may see this format is when you view stack
traces, where you may encounter traces of the format
+[source, text]
....
java.lang.NullPointerException
at Main.new$constructor_call37(Main.java;SynchAspect.java[1k]:1030)
@@ -461,12 +477,14 @@ java.lang.NullPointerException
where instead of the usual
+[source, text]
....
File:LineNumber
....
format, you see
+[source, text]
....
File0;File1[Number1];File2[Number2] ... :LineNumber
....
diff --git a/docs/devGuideDB/ajdb.adoc b/docs/devGuideDB/ajdb.adoc
index f1b02d910..4e45cbc80 100644
--- a/docs/devGuideDB/ajdb.adoc
+++ b/docs/devGuideDB/ajdb.adoc
@@ -133,7 +133,7 @@ Pass a non-standard option to the VM
=== Capabilities
-The AspectJ debugger implements all of `jdb`'s commands. In addition,
+The AspectJ debugger implements all of ``jdb``'s commands. In addition,
the command `workingdir` allow you to set the AspectJ working directory,
and the breakpoint command, `stop on`, has been extended to allow the
setting of breakpoint on a source file line.
@@ -158,25 +158,25 @@ For this example, we need to set the source path by: `
To view the file to debug, type `list
spacewar/Ship.java` which generates the following output:
+[source, java]
....
-209 void fire() {
-210 // firing a shot takes energy
-211 if (!expendEnergy(BULLET_ENERGY))
-212 return;
-213
-214 //create a bullet object so it doesn't hit the ship that's firing it
-215 double xV = getXVel() + BULLET_SPEED * (Math.cos(orientation));
-216 double yV = getYVel() + BULLET_SPEED * (Math.sin(orientation));
-217
-218 // create the actual bullet
-219 new Bullet(
-220 getGame(),
-221 (getXPos() + ((getSize()/2 + 2) * (Math.cos(orientation))) + xV),
-222 (getYPos() + ((getSize()/2 + 2) * (Math.sin(orientation))) + yV),
-223 xV,
-224 yV);
-225 }
-
+/*209*/ void fire() {
+/*210*/ // firing a shot takes energy
+/*211*/ if (!expendEnergy(BULLET_ENERGY))
+/*212*/ return;
+/*213*/
+/*214*/ //create a bullet object so it doesn't hit the ship that's firing it
+/*215*/ double xV = getXVel() + BULLET_SPEED * (Math.cos(orientation));
+/*216*/ double yV = getYVel() + BULLET_SPEED * (Math.sin(orientation));
+/*217*/
+/*218*/ // create the actual bullet
+/*219*/ new Bullet(
+/*220*/ getGame(),
+/*221*/ (getXPos() + ((getSize()/2 + 2) * (Math.cos(orientation))) + xV),
+/*222*/ (getYPos() + ((getSize()/2 + 2) * (Math.sin(orientation))) + yV),
+/*223*/ xV,
+/*224*/ yV);
+/*225*/ }
....
This is different from `jdb` because it allows one to view files before
@@ -222,88 +222,88 @@ The following message appears notifying the user that the breakpoint has
been noted but will not be set until the class has been loaded by the
VM:
+[source, text]
....
Deferring breakpoint spacewar.Ship.fire()
It will be set after the class is loaded.
-
....
To start Spacewar we type `run spacewar.Game`.
When the breakpoint is set, the following message appears:
+[source, text]
....
Set deferred breakpoint spacewar.Ship.fire()
-
....
We are notified that we've hit the breakpoint:
+[source, text]
....
Breakpoint hit: thread="Thread-2", spacewar.Ship.fire(), line=174, bci=0 209 void fire() {
-
....
The prompt changes to present the thread that has broken, and we can
view the current stack with the `where` command, as follows:
+[source, text]
....
Thread-2[1] where
[1] fire (spacewar\Ship.java:209)
[2] run (spacewar\Robot.java:100)
[3] run [class java.lang.Thread]
-
....
Next, to stop on line 216 we type `stop on spacewar/Ship.java:216`
The following message tells us the breakpoint was set:
+[source, text]
....
Set breakpoint Ship.java:216
-
....
To continue execution, we type `cont` and the breakpoint at line 216 is
hit
+[source, text]
....
Breakpoint hit: thread="Thread-2", spacewar.Ship.fire(), line=216, bci=28
216 double yV = getYVel() + BULLET_SPEED * (Math.sin(orientation));
-
....
To view the visible local variables, we type `locals` and ajdb responds
with:
+[source, text]
....
Local variables
xV = 12.242462584304468
-
....
To change the value of the local variable i to 15, we type
`set xV = 16.1`
+[source, text]
....
Changed 'xV' from '12.242462584304468' to '16.1'
-
....
To see our changes we can print the value of `i` by the following:
+[source, text]
....
print xV
Value for printing 'xV' = 12.242462584304468
-
....
We can now type exit or quit to leave the debugger, and we receive the
following message:
+[source, text]
....
The application has exited.
-
....
=== The AspectJ debugger API
@@ -314,13 +314,10 @@ the method `org.aspectj.tools.debugger.Main.main(String[]
args)` where `args` are the standard `ajc` command line arguments.
This means that an alternative way to run the compiler is
-java org.aspectj.tools.debugger.Main
-
-option
-
-class
-
-arguments
+[source, text]
+....
+java org.aspectj.tools.debugger.Main options class arguments
+....
You must additionally include `tools.jar` from your Java developer's kit
in your classpath.
diff --git a/docs/devGuideDB/ajdee.adoc b/docs/devGuideDB/ajdee.adoc
index 9d8963179..ca6df3d66 100644
--- a/docs/devGuideDB/ajdee.adoc
+++ b/docs/devGuideDB/ajdee.adoc
@@ -123,6 +123,7 @@ enable AspectJ mode on a per-project basis.
your `load-path` and are ``required''. This is an example for the 1.0
release:
+
+[source, text]
....
;; I keep my emacs packages in C:/Emacs
(setq load-path
@@ -140,7 +141,6 @@ load-path))
(require 'jde)
(require 'ajdee) ; can also appear in prj.el
-
....
. _[Optional]_ add `-emacssym` switch to the `ajc` and `ajc.bat` files
in your AspectJ tools installations (in the `/bin` directory). If you
@@ -152,6 +152,7 @@ following in your `.emacs` file or in a JDE project file `prj.el` in
your project's hierarchy (see the `JDE Project File Name` option for the
latter). Here is a simple example:
+
+[source, text]
....
;; A default version for simple projects, maybe good for
;;; .emacs file.
@@ -161,11 +162,11 @@ latter). Here is a simple example:
;; ajc requires all files to be named for a compile
'(aspectj-compile-file-specification "*.java"))
-
....
+
Here is an example for spacewar, in `examples/spacewar`.
+
+[source, text]
....
;;; These options are for the spacewar, in examples/spacewar.
(custom-set-variables
@@ -180,7 +181,6 @@ Here is an example for spacewar, in `examples/spacewar`.
'(jde-compile-option-directory "..")
'(jde-run-working-directory ".."))
'(jde-run-application-class "spacewar.Game")
-
....
. _[XEmacs only]_ If you're installing JDE yourself, be sure to closely
follow the JDE installation directions for XEmacs, otherwise you may get
@@ -207,6 +207,7 @@ for problems not specific to AJDEE's features.
* _Symptom_: Get standard speedbar menus in JDE; no annotations display.
Message:
+
+[source, text]
....
AspectJ Mode Warning: Can't find declarations file for...
....
@@ -235,6 +236,7 @@ AspectJ project's directory (see sample.prj in the distribution).
* _Symptom_: Reported bug fixes and new features to AJDEE are not seen,
or ajdee.el cannot be found or loaded, with message:
+
+[source, text]
....
Error in init file: File error: "Cannot open load file", "ajdee"
....
diff --git a/docs/devGuideDB/ajdoc.adoc b/docs/devGuideDB/ajdoc.adoc
index 2a929e3db..6bea2ff16 100644
--- a/docs/devGuideDB/ajdoc.adoc
+++ b/docs/devGuideDB/ajdoc.adoc
@@ -34,6 +34,7 @@ argfile (`@filename`) conventions as with `ajc`. For example, the
following documents all the source files listed in `argfile.lst`,
sending the output to the `docDir` output directory.
+[source, text]
....
ajdoc -d docDir @argfile.lst
....
diff --git a/docs/devGuideDB/antsupport.adoc b/docs/devGuideDB/antsupport.adoc
index 12de6f296..1bc9b6f70 100644
--- a/docs/devGuideDB/antsupport.adoc
+++ b/docs/devGuideDB/antsupport.adoc
@@ -38,6 +38,7 @@ in `${ANT_HOME}/lib` where it will be added to the system class path by
the ant script. You may specify the task script names directly, or use
the "resource" attribute to specify the default names:
+[source, xml]
....
<taskdef resource="org/aspectj/tools/ant/taskdefs/aspectjTaskdefs.properties"/>
....
@@ -50,6 +51,7 @@ In Ant 1.6, third-party tasks are declared in their own namespace using
spacewar example, if you put the script in the examples directory and
`aspectjtools.jar` in the `${ANT_HOME}/lib` directory.
+[source, xml]
....
<project name="aspectj-ant1.6" default="spacewar"
xmlns:aspectj="antlib:org.aspectj" basedir=".">
@@ -340,6 +342,7 @@ elements; these are `sourceroots`, `argfiles`, `injars`, `inpath`,
`classpath`, `bootclasspath`, `forkclasspath`, and `aspectpath`. In all
cases, these may be specified as nested elements, something like this:
+[source, xml]
....
<iajc {attributes..} />
<{name}>
@@ -354,6 +357,7 @@ cases, these may be specified as nested elements, something like this:
As with other Path-like structures, they may be defined elsewhere and
specified using the refid attribute:
+[source, xml]
....
<path id="aspect.path">
<pathelement path="${home}/lib/persist.jar"/>
@@ -369,6 +373,7 @@ specified using the refid attribute:
The task also supports an attribute `{name}ref` for each such parameter.
E.g., for `aspectpath`:
+[source, xml]
....
<iajc {attributes..} aspectpathref="aspect.path"/>
....
@@ -379,6 +384,7 @@ E.g., for `aspectpath`:
A minimal build script defines the task and runs it, specifying the
sources:
+[source, xml]
....
<project name="simple-example" default="compile" >
<taskdef
@@ -410,6 +416,7 @@ When this target is built, the compiler will build once and then wait
for input from the user. Messages are printed as usual. When the user
has quit, then this runs the application.
+[source, xml]
....
<target name="build-test" >
<iajc outjar="${home.dir}/output/application.jar"
@@ -453,6 +460,7 @@ case where no files have been updated, there is no reason to recompile
sources. One way to implement that is with an explicit dependency check
using the uptodate task:
+[source, xml]
....
<target name="check.aspects.jar">
<uptodate property="build.unnecessary"
@@ -512,6 +520,7 @@ example, the call below passes all out-of-date source files in the
`src/org/aspectj` subdirectories to the `ajc` command along with the
destination directory:
+[source, text]
....
-- command:
@@ -525,6 +534,7 @@ destination directory:
To pass ajc-specific arguments, use a compilerarg entry.
+[source, text]
....
-- command
@@ -598,6 +608,7 @@ This tells the compiler adapter to delete all .class files in the
destination directory and re-execute the javac task so javac can
recalculate the list of source files. e.g.,
+
+[source, text]
....
Ant -Dbuild.compiler=org.aspectj.tools.ant.taskdefs.Ajc11CompilerAdapter
-Dbuild.compiler.clean=anything ...
@@ -746,7 +757,7 @@ This task forms an implicit FileSet and supports all attributes of
`<exclude>`, and `<patternset>` elements. These can be used to specify
source files.
-`ajc`'s `srcdir`, `classpath`, `bootclasspath`, `extdirs`, and `jvmarg`
+``ajc``'s `srcdir`, `classpath`, `bootclasspath`, `extdirs`, and `jvmarg`
attributes are path-like structures and can also be set via nested
`<src>`, `<classpath>`, `<bootclasspath>`, `<extdirs>`, and `<jvmargs>`
elements, respectively.
@@ -758,6 +769,7 @@ Following is a declaration for the ajc task and a sample invocation that
uses the ajc compiler to compile the files listed in `default.lst` into
the dest dir:
+[source, xml]
....
<project name="example" default="compile" >
<taskdef name="ajc"
@@ -782,6 +794,7 @@ the dest dir:
This build script snippet
+[source, xml]
....
<ajc srcdir="${src}"
destdir="${build}"
@@ -796,6 +809,7 @@ are included.
This next example
+[source, xml]
....
<ajc srcdir="${src}"
destdir="${build}"
diff --git a/docs/devGuideDB/aspectj-mode.adoc b/docs/devGuideDB/aspectj-mode.adoc
index e4d09acdd..4c585ed2c 100644
--- a/docs/devGuideDB/aspectj-mode.adoc
+++ b/docs/devGuideDB/aspectj-mode.adoc
@@ -103,11 +103,11 @@ initialization file `sample.emacs` in the distribution.
. The files in this package need to be in the load-path and
``required''. For example, for the 1.0 release:
+
+[source, text]
....
;; I keep my emacs packages in C:/Emacs
(setq load-path (cons "C:/Emacs/aspectj-emacsMode-1.0" load-path))
(require 'aspectj-mode)
-
....
. _[Optional]_ add `-emacssym` switch to the `ajc` and `ajc.bat` files
in your AspectJ tools installations (in the `/bin` directory). If you
@@ -130,6 +130,7 @@ given in the file `sample.emacs` in the distribution.
* _Symptom_: No annotations show. Message:
+
+[source, text]
....
AspectJ Mode Warning: Can't find declarations file for...
....
@@ -160,6 +161,7 @@ menu.
* _Symptom_: Reported bug fixes and new features to aspectj-mode are not
seen, or aspectj-mode.el cannot be found or loaded, with message:
+
+[source, text]
....
Error in init file: File error: "Cannot open load file", "aspectj-mode"
....
diff --git a/docs/devGuideDB/ltw.adoc b/docs/devGuideDB/ltw.adoc
index ac58dfca7..7b216ba76 100644
--- a/docs/devGuideDB/ltw.adoc
+++ b/docs/devGuideDB/ltw.adoc
@@ -125,6 +125,7 @@ Aspects defined in this way must extend an abstract aspect visible to
the weaver. The abstract aspect may define abstract pointcuts (but not
abstract methods). The following example shows a simple aop.xml file:
+[source, xml]
....
<aspectj>
@@ -260,6 +261,7 @@ pointcuts at deployment time, and also gives control over precedence
through the `precedence` attribute of the `concrete-aspect` XML element.
Consider the following:
+[source, java]
....
package mypack;
@@ -272,13 +274,14 @@ public abstract class AbstractAspect {
@Before("scope() && execution(* *..doSome(..))")
public void before(JoinPoint jp) {
- ....
+ // ...
}
}
....
This aspect is equivalent to the following in code style:
+[source, java]
....
package mypack;
@@ -288,7 +291,7 @@ public abstract aspect AbstractAspect {
abstract pointcut scope();
before() : scope() && execution(* *..doSome(..)) {
- ....
+ // ...
}
}
....
@@ -318,6 +321,7 @@ If more complex aspect inheritance is required use regular aspect
inheritance instead of XML. The following XML definition shows a valid
concrete sub-aspect for the abstract aspects above:
+[source, xml]
....
<aspectj>
<aspects>
@@ -339,6 +343,7 @@ aspect instance(s) (depending on the perclause of the aspect it extends)
you have to use the helper API `org.aspectj.lang.Aspects.aspectOf(..)`
as in:
+[source, java]
....
// exception handling omitted
Class myConcreteAspectClass = Class.forName("mypack.__My__AbstractAspect");
@@ -359,6 +364,7 @@ abstract aspect. It is therefore possible to use the `concrete-aspect`
element without the `extends` attribute and without any `pointcut`
nested elements, just a `precedence` attribute. Consider the following:
+[source, xml]
....
<aspectj>
<aspects>
@@ -459,6 +465,7 @@ weaving configuration files.
When using Java 5 the JVMTI agent can be used by starting the JVM with
the following option (adapt according to the path to aspectjweaver.jar):
+[source, text]
....
-javaagent:pathto/aspectjweaver.jar
....
diff --git a/docs/developer/amcDesignNotes.adoc b/docs/developer/amcDesignNotes.adoc
index 47cf6960b..77b0dd2d9 100644
--- a/docs/developer/amcDesignNotes.adoc
+++ b/docs/developer/amcDesignNotes.adoc
@@ -4,6 +4,7 @@ _Last updated: 2004-03-15 by acolyer_
== How Compilation Progresses in the JDT
+[source, text]
....
Compiler.compile(ICompilationUnit[] sourceUnits) {
@@ -35,6 +36,7 @@ passed to the compiler, and the code generation phase is optional
== How (batch) Compilation Progresses in AspectJ 1.1.x
+[source, text]
....
AjBuildManager.doBuild() {
@@ -90,6 +92,7 @@ that do different things).
This simple model ignores aspectpath, inpath, injars, outjar,
sourceDirs for now.
+[source, text]
....
Compiler.compile(ICompilationUnit[] sourceUnits) {
diff --git a/docs/developer/compiler-weaver/index.adoc b/docs/developer/compiler-weaver/index.adoc
index 1443370f1..817656e35 100644
--- a/docs/developer/compiler-weaver/index.adoc
+++ b/docs/developer/compiler-weaver/index.adoc
@@ -65,6 +65,7 @@ code generation
Let's trace the following example program through the compiler.
+[source, java]
....
package example.parse.tree;
@@ -99,6 +100,7 @@ image:top-tree.gif[image]
Let's look more closely at the pointcut declaration:
+[source, java]
....
pointcut entries(Main o): execution(void doit()) && this(o);
....
@@ -114,6 +116,7 @@ information might be needed to implement a declare soft.
Next we look at the processing for an advice declaration:
+[source, java]
....
before(Main o): entries(o) {
o.counter++;
@@ -262,6 +265,7 @@ failures, resolve them with the AspectJ developers before moving on.
{empty}a. Create a new file in tests/design/pcds/Throw.java
+[source, java]
....
import org.aspectj.testing.Tester;
@@ -290,6 +294,7 @@ aspect A {
{empty}b. Create a temporary test harness file to run just this test in
myTests.xml
+[source, xml]
....
<!DOCTYPE suite SYSTEM "../tests/ajcTestSuite.dtd">
<suite>
@@ -303,6 +308,7 @@ myTests.xml
{empty}c. Run this test using the harness. You should see:
+[source, text]
....
about to execute: execution(void Throws.willThrow())
about to execute: call(java.lang.RuntimeException(String))
@@ -314,6 +320,7 @@ PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 2 seconds
Modify runtime/org.aspectj.lang/JoinPoint.java to add a name for the
Throw shadow kind.
+[source, java]
....
static String THROW = "throw";
....
@@ -328,6 +335,7 @@ This is because the throw bytecode in Java operates on a single argument
that is a Throwable which must be the top element on the stack. This
argument is removed from the stack by the bytecode.
+[source, java]
....
public static final Kind Throw = new Kind(JoinPoint.THROW, 12, true);
....
@@ -335,6 +343,7 @@ public static final Kind Throw = new Kind(JoinPoint.THROW, 12, true);
We also modify the neverHasTarget method to include the Throw kind
because in Java there is no target for the throwing of an exception.
+[source, java]
....
public boolean neverHasTarget() {
return this == ConstructorCall
@@ -348,6 +357,7 @@ public boolean neverHasTarget() {
In the read method on Shadow.Kind, add another case to read in our new
Shadow.Kind.
+[source, java]
....
case 12: return Throw;
....
@@ -357,6 +367,7 @@ case 12: return Throw;
Modify weaver/org.aspectj.weaver.bcel/BcelClassWeaver.java to recognize
this new joinpoint kind. In the method
+[source, java]
....
private void match(
LazyMethodGen mg,
@@ -368,6 +379,7 @@ private void match(
Add a test for this instruction, i.e.
+[source, java]
....
} else if (i == InstructionConstants.ATHROW) {
match(BcelShadow.makeThrow(world, mg, ih, enclosingShadow),
@@ -378,6 +390,7 @@ Add a test for this instruction, i.e.
Then, modify BcelShadow.java to create this new kind of join point
shadow:
+[source, java]
....
public static BcelShadow makeThrow(
BcelWorld world,
@@ -408,6 +421,7 @@ public static BcelShadow makeThrow(
Finally modify weaver/org.aspectj.weaver/Member.java to generate the
needed signature
+[source, java]
....
public static Member makeThrowSignature(TypeX inType, TypeX throwType) {
return new Member(
@@ -421,6 +435,7 @@ public static Member makeThrowSignature(TypeX inType, TypeX throwType) {
Run the proto test again and you should see:
+[source, text]
....
about to execute: execution(void Throws.willThrow())
about to execute: call(java.lang.RuntimeException(String))
@@ -439,6 +454,7 @@ part of the clean-up. For now, let's go on with the interesting parts.
Add a second piece of before advice to the test aspect A:
+[source, java]
....
before(): throw(Throwable) {
System.out.println("about to throw: " + thisJoinPoint);
@@ -448,6 +464,7 @@ before(): throw(Throwable) {
When we run the test again we'll get a long error message from the
harness. The interesting part of the message is the following:
+[source, text]
....
[ 0] [error 0]: error can't find referenced pointcut at C:\aspectj\eclipse\tests\design\pcds\Throws.java:23:0
....
@@ -470,6 +487,7 @@ Modify the parseSinglePointcut method in
weaver/org.aspectj.weaver.patterns/PatternParser.java to add one more
else if clause for the throw pcd:
+[source, java]
....
} else if (kind.equals("throw")) {
parseIdentifier(); eat("(");
@@ -485,6 +503,7 @@ else if clause for the throw pcd:
Modify the matches method in
weaver/org.aspectj.weaver.patterns/SignaturePattern.java to add:
+[source, java]
....
if (kind == Member.HANDLER) {
return parameterTypes.matches(world.resolve(sig.getParameterTypes()),
@@ -494,6 +513,7 @@ if (kind == Member.HANDLER) {
Run the proto test again and you should see:
+[source, text]
....
about to execute: execution(void Throws.willThrow())
about to execute: call(java.lang.RuntimeException(String))
@@ -513,6 +533,7 @@ case. Modify our test aspect A to be the following. In addition to
removing the overly generic withincode pcd, this change also prints the
actual object that is about to be thrown:
+[source, java]
....
aspect A {
before(Throwable t): throw(*) && args(t) {
@@ -523,6 +544,7 @@ aspect A {
When we run the test again we should see the output below:
+[source, text]
....
about to throw: 'java.lang.RuntimeException: expected exception' at throw(catch(Throwable))
PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 1 seconds
@@ -546,6 +568,7 @@ exception thrown to be 'Throwable'. Can we set this to be more accurate?
Looking at the source code, it seems easy to identify the static type of
the exception that is thrown:
+[source, java]
....
throw new RuntimeException("expected exception");
....
@@ -585,6 +608,7 @@ thrown, we need to fix the parser for the throw pcd to remove this
information. We'll fix the PatternParser code that we added in step 1.6
to read as follows:
+[source, java]
....
} else if (kind.equals("throw")) {
parseIdentifier(); eat("(");
@@ -602,6 +626,7 @@ before. To make this work we have a set of things to do. First, let's
create this new kind in org.aspectj.weaver.Member. Find where the
HANDLER kind is defined there, and add a corresponding throw kind:
+[source, java]
....
public static final Kind THROW = new Kind("THROW", 8);
....
@@ -610,6 +635,7 @@ We also need to fix the serialization kind in
Member.Kind.read(DataInputStream) just above this constant list to add a
case for this new kind:
+[source, java]
....
case 8: return THROW;
....
@@ -617,6 +643,7 @@ case 8: return THROW;
Still in this file, we also need to fix Member.makeThrowSignature to use
this new kind:
+[source, java]
....
public static Member makeThrowSignature(TypeX inType, TypeX throwType) {
return new ResolvedMember(
@@ -631,6 +658,7 @@ public static Member makeThrowSignature(TypeX inType, TypeX throwType) {
If you run the test now you'll get an error from the parser reminding us
that the throw pcd now doesn't accept a type pattern:
+[source, text]
....
------------ FAIL: simple throw join point()
...
@@ -642,6 +670,7 @@ FAIL Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 failed) 1 seconds
This is an easy fix to the test case as we modify our pcd for the new
syntax in the aspect A in our Throws.java test code:
+[source, java]
....
before(Throwable t): throw() && args(t) {
....
@@ -649,6 +678,7 @@ before(Throwable t): throw() && args(t) {
Now when we run the test case it looks like everything's fixed and we're
passing:
+[source, text]
....
PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 2 seconds
....
@@ -664,6 +694,7 @@ that by adding code that notes when the advice runs and then checks for
this event. This code uses the Tester.event and Tester.checkEvent
methods:
+[source, java]
....
import org.aspectj.testing.Tester;
@@ -694,6 +725,7 @@ aspect A {
Now when we run our test case it will fail. This failure is good because
we're not matching the throw join point anymore.
+[source, text]
....
------------ FAIL: simple throw join point()
...
@@ -711,6 +743,7 @@ use combinations with other pcds to narrow their matches. So, find the
line for kind == Member.ADVICE and add the same line below it for
Member.THROW.
+[source, java]
....
if (kind == Member.ADVICE) return true;
if (kind == Member.THROW) return true;
@@ -727,6 +760,7 @@ kind of printing back on the see what's happening. If you uncomment to
System.out.println in the test aspect A and rerun the test, you won't be
very happy with the results:
+[source, text]
....
------------ FAIL: simple throw join point()
...
@@ -752,6 +786,7 @@ signature, these classes are extremely simple. Nevertheless, we have to
build them. Notice that when we add new source files to the system we
need to include the standard eclipse EPL license header.
+[source, java]
....
/* *******************************************************************
* Copyright (c) 2006 Contributors.
@@ -771,6 +806,7 @@ import org.aspectj.lang.Signature;
public interface ThrowSignature extends Signature { }
....
+[source, java]
....
/* *******************************************************************
* Copyright (c) 2006 Contributors.
@@ -807,6 +843,7 @@ To finish up our work in the runtime module, we need to extend
org.aspectj.runtime.reflect.Factory to add a factory method for this new
signature kind:
+[source, java]
....
public ThrowSignature makeThrowSig(String stringRep) {
ThrowSignatureImpl ret = new ThrowSignatureImpl(stringRep);
@@ -822,6 +859,7 @@ first place. First let's add a method to create a string for the throw
signature. This is a very simple method copied from the other
create*SignatureString methods.
+[source, java]
....
private String getThrowSignatureString(World world) {
StringBuffer buf = new StringBuffer();
@@ -836,6 +874,7 @@ private String getThrowSignatureString(World world) {
Now we need to modify three methods to add cases for the new
Member.THROW kind. First, Member.getSignatureMakerName add:
+[source, java]
....
} else if (kind == THROW) {
return "makeThrowSig";
@@ -843,6 +882,7 @@ Member.THROW kind. First, Member.getSignatureMakerName add:
Next, to Member.getSignatureType add:
+[source, java]
....
} else if (kind == THROW) {
return "org.aspectj.lang.reflect.ThrowSignature";
@@ -850,6 +890,7 @@ Next, to Member.getSignatureType add:
Finally, to Member.getSignatureString add:
+[source, java]
....
} else if (kind == THROW) {
return getThrowSignatureString(world);
@@ -859,6 +900,7 @@ With all of these changes in place we should have working code for
thisJoinPoint reflection using our new join point and signature kinds.
Rerun the test to confirm:
+[source, text]
....
about to throw: 'java.lang.RuntimeException: expected exception' at throw(throw)
PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 1 seconds
@@ -869,6 +911,7 @@ PASS Suite.Spec(c:\aspectj\eclipse\tests) 1 tests (1 passed) 1 seconds
Modify the before advice to include at least minimal checks of the new
reflective information:
+[source, java]
....
before(Throwable t): throw() && args(t) {
Tester.event("before throw");
@@ -908,6 +951,7 @@ tests.
You should expect to see at least one other test case fail when you run
ajcTests.xml. Here's the failure message:
+[source, text]
....
------------ FAIL: validate (enclosing) join point and source locations()
...
@@ -948,6 +992,7 @@ that the only occurence of throw is just before the handler for
catch(Error) and right after the call to new Error. We should add our
new expected event between these two:
+[source, text]
....
, "before AllTargetJoinPoints call(java.lang.Error(String))"
, "before AllTargetJoinPoints throw(throw)" // added for new throw join point
@@ -964,6 +1009,7 @@ to make sure that the new join point kind is compatible with all 5 kinds
of advice. Let's extend our current simple Throws test to check for
before and the three kinds of after advice:
+[source, java]
....
import org.aspectj.testing.Tester;
@@ -1019,6 +1065,7 @@ point kind work for before and all three kinds of after advice.
Let's create a new test case to see how this new join point interacts
with around advice.
+[source, java]
....
import org.aspectj.testing.Tester;
@@ -1050,6 +1097,7 @@ aspect A {
When we run this test case we get a very unpleasant result:
+[source, text]
....
------------ FAIL: simple throw join point with around()
...
@@ -1080,6 +1128,7 @@ implemented in the org.aspectj.weaver.Shadow.match(Shadow, World)
method. We can add our new rule at the beginning of the if(kind ==
AdviceKind.Around) block:
+[source, java]
....
} else if (kind == AdviceKind.Around) {
if (shadow.getKind() == Shadow.Throw) {
@@ -1093,6 +1142,7 @@ AdviceKind.Around) block:
Now if we rerun our test we'll see errors telling us that around is
prohibited on throw join points:
+[source, text]
....
------------ FAIL: simple throw join point with around()
...
@@ -1106,6 +1156,7 @@ To finish this test case up we need to modify the specification to be
looking for these errors as the correct behavior. This will produce the
following specification:
+[source, xml]
....
<ajc-test dir="design/pcds"
title="simple throw join point with around">
diff --git a/docs/dist/LICENSE-AspectJ.adoc b/docs/dist/LICENSE-AspectJ.adoc
index 9a2a163d6..9b874e58f 100644
--- a/docs/dist/LICENSE-AspectJ.adoc
+++ b/docs/dist/LICENSE-AspectJ.adoc
@@ -50,6 +50,7 @@ http://asm.objectweb.org/download/.
The ASM license is available at http://asm.objectweb.org/license.html.
The license is also reproduced here:
+[source, text]
....
Copyright (c) 2000-2005 INRIA, France Telecom
All rights reserved.
diff --git a/docs/dist/doc/README-11.adoc b/docs/dist/doc/README-11.adoc
index 377d18588..1843f38be 100644
--- a/docs/dist/doc/README-11.adoc
+++ b/docs/dist/doc/README-11.adoc
@@ -288,22 +288,21 @@ In AspectJ 1.0.6, we made an effort to hide some complications with
Aspect instantiation from the user. In particular, the following code
compiled and ran:
+[source, java]
....
- public class Client
- {
- public static void main(String[] args) {
- Client c = new Client();
- }
- }
-
- aspect Watchcall {
- pointcut myConstructor(): execution(new(..));
+public class Client {
+ public static void main(String[] args) {
+ Client c = new Client();
+ }
+}
- before(): myConstructor() {
- System.err.println("Entering Constructor");
- }
- }
+aspect Watchcall {
+ pointcut myConstructor(): execution(new(..));
+ before(): myConstructor() {
+ System.err.println("Entering Constructor");
+ }
+}
....
But there's a conceptual problem with this code: The before advice
@@ -317,25 +316,24 @@ preventing an aspect's advice from matching join points that were within
the aspect's definition, and occurred before the aspect was initialized.
But even in AspectJ 1.0.6, this circularity could be exposed:
+[source, java]
....
- public class Client
- {
- public static int foo() { return 3; }
- public static void main(String[] args) {
- Client c = new Client();
- }
- }
-
- aspect Watchcall {
- int i = Client.foo();
- pointcut myConstructor():
- execution(new(..)) || execution(int foo());
+public class Client {
+ public static int foo() { return 3; }
+ public static void main(String[] args) {
+ Client c = new Client();
+ }
+}
- before(): myConstructor() {
- System.err.println("Entering Constructor");
- }
- }
+aspect Watchcall {
+ int i = Client.foo();
+ pointcut myConstructor():
+ execution(new(..)) || execution(int foo());
+ before(): myConstructor() {
+ System.err.println("Entering Constructor");
+ }
+}
....
This program would throw a NullPointerException when run, since
@@ -356,29 +354,29 @@ Type patterns may now be used to pick out methods and constructors based
on their throws clauses. This allows the following two kinds of
extremely wildcarded pointcuts:
+[source, java]
....
- pointcut throwsMathlike():
- // each call to a method with a throws clause containing at least
- // one exception with "Math" in its name.
- call(* *(..) throws *..*Math*);
-
- pointcut doesNotThrowMathlike():
- // each call to a method with a throws clause containing no
- // exceptions with "Math" in its name.
- call(* *(..) throws !*..*Math*);
+pointcut throwsMathlike():
+ // each call to a method with a throws clause containing at least
+ // one exception with "Math" in its name.
+ call(* *(..) throws *..*Math*);
+pointcut doesNotThrowMathlike():
+ // each call to a method with a throws clause containing no
+ // exceptions with "Math" in its name.
+ call(* *(..) throws !*..*Math*);
....
The longwinded rules are that a method or constructor pattern can have a
"throws clause pattern". Throws clause patterns look like:
+[source, text]
....
- ThrowsClausePattern:
- ThrowsClausePatternItem ("," ThrowsClausePatternItem)*
-
- ThrowsClausePatternItem:
- ["!"] TypeNamePattern
+ThrowsClausePattern:
+ ThrowsClausePatternItem ("," ThrowsClausePatternItem)*
+ThrowsClausePatternItem:
+ ["!"] TypeNamePattern
....
A ThrowsClausePattern matches the ThrowsClause of any code member
@@ -398,12 +396,12 @@ These rules are completely backwards compatible with AspectJ 1.0. The
rule for "!" matching has one potentially surprising property, in that
the two PCD's shown below will have different matching rules.
+[source, java]
....
- [1] call(* *(..) throws !IOException)
- [2] call(* *(..) throws (!IOException))
-
- void m() throws RuntimeException, IOException {}
+/*[1]*/ call(* *(..) throws !IOException)
+/*[2]*/ call(* *(..) throws (!IOException))
+void m() throws RuntimeException, IOException {}
....
[1] will NOT match the method m(), because method m's throws clause
@@ -439,31 +437,31 @@ xref:#SINGLE_INTERCLASS_TARGET[restrictions on inter-type declarations]
. This is also motivated by many previous request to support a common
logging idiom. Here's what pertype would look like:
+[source, java]
....
- /** One instance of this aspect will be created for each class,
- * interface or aspect in the com.bigboxco packages.
- */
- aspect Logger pertype(com.bigboxco..*) {
- /* This field holds a logger for the class. */
- Log log;
-
- /* This advice will run for every public execution defined by
- * a type for which a Logger aspect has been created, i.e.
- * any type in com.bigboxco..*
- */
- before(): execution(public * *(..)) {
- log.enterMethod(thisJoinPoint.getSignature().getName());
- }
+/** One instance of this aspect will be created for each class,
+ * interface or aspect in the com.bigboxco packages.
+ */
+aspect Logger pertype(com.bigboxco..*) {
+ /* This field holds a logger for the class. */
+ Log log;
- /* We can use a special constructor to initialize the log field */
- public Logger(Class myType) {
- this.log = new Log(myType);
- }
+ /* This advice will run for every public execution defined by
+ * a type for which a Logger aspect has been created, i.e.
+ * any type in com.bigboxco..*
+ */
+ before(): execution(public * *(..)) {
+ log.enterMethod(thisJoinPoint.getSignature().getName());
}
- /** External code could use aspectOf to get at the log, i.e. */
- Log l = Logger.aspectOf(com.bigboxco.Foo.class).log;
+ /* We can use a special constructor to initialize the log field */
+ public Logger(Class myType) {
+ this.log = new Log(myType);
+ }
+}
+/** External code could use aspectOf to get at the log, i.e. */
+Log l = Logger.aspectOf(com.bigboxco.Foo.class).log;
....
The one open question that we see is how this should interact with inner
@@ -481,23 +479,23 @@ only have one target type. So the following code intended to declare
that there is a void doStuff() method on all subtypes of Target is not
legal AspectJ 1.1 code.
+[source, java]
....
- aspect A {
- public void Target+.doStuff() { ... }
- }
-
+aspect A {
+ public void Target+.doStuff() { ... }
+}
....
The functionality of "multi-intertype declarations" can be recovered by
using a helper interface.
+[source, java]
....
- aspect A {
- private interface MyTarget {}
- declare parents: Target+ implements MyTarget;
- public void MyTarget.doStuff() { ... }
- }
-
+aspect A {
+ private interface MyTarget {}
+ declare parents: Target+ implements MyTarget;
+ public void MyTarget.doStuff() { ... }
+}
....
We believe this is better style in AspectJ 1.0 as well, as it makes
@@ -531,18 +529,19 @@ The code generated by the initializers in Java source code now runs
inside of constructor execution join points. This changes how before
advice runs on constructor execution join points. Consider:
+[source, java]
....
- class C {
- C() { }
- String id = "identifier"; // this assignment
- // has to happen sometime
- }
- aspect A {
- before(C c) this(c) && execution(C.new()) {
- System.out.println(c.id.length());
- }
- }
+class C {
+ C() { }
+ String id = "identifier"; // this assignment
+ // has to happen sometime
+}
+aspect A {
+ before(C c) this(c) && execution(C.new()) {
+ System.out.println(c.id.length());
+ }
+}
....
In AspectJ 1.0, this will print "10", since id is assigned its initial
@@ -579,10 +578,10 @@ initialization (i.e., before initializers from the target class) or at
the end (i.e., just before its called constructor exits). We chose the
former, having this pattern in mind:
+[source, java]
....
- int C.methodCount = 0;
- before(C c): this(c) && execution(* *(..)) { c.methodCount++; }
-
+int C.methodCount = 0;
+before(C c): this(c) && execution(* *(..)) { c.methodCount++; }
....
We felt there would be too much surprise if a constructor called a
@@ -604,25 +603,25 @@ C, below), if given a member-type (like C.InsideC, below), it is not
guaranteed to capture code in contained local and anonymous types. For
example:
-....
- class C {
- Thread t;
- class InsideC {
- void setupOuterThread() {
- t = new Thread(
- new Runnable() {
- public void run() {
- // join points with code here
- // might not be captured by
- // within(C.InsideC), but are
- // captured by within(C)
- System.out.println("hi");
- }
- });
- }
+[source, java]
+....
+class C {
+ Thread t;
+ class InsideC {
+ void setupOuterThread() {
+ t = new Thread(
+ new Runnable() {
+ public void run() {
+ // join points with code here
+ // might not be captured by
+ // within(C.InsideC), but are
+ // captured by within(C)
+ System.out.println("hi");
+ }
+ });
}
}
-
+}
....
We believe the non-guarantee is small, and we haven't verified that it
@@ -642,9 +641,9 @@ their argument. These tests can not be performed on type patterns with
wildcards in them. The following code that compiled under 1.0 will be an
error in AspectJ-1.1:
+[source, java]
....
- pointcut oneOfMine(): this(com.bigboxco..*);
-
+pointcut oneOfMine(): this(com.bigboxco..*);
....
The only way to implement this kind of matching in a modular way would
@@ -653,27 +652,27 @@ would have a very high performance cost and possible security issues.
There are two good work-arounds. If you control the source or bytecode
to the type you want to match then you can use declare parents, i.e.:
+[source, java]
....
- private interface OneOfMine {}
- declare parents: com.bigboxco..* implements OneOfMine;
- pointcut oneOfMine(): this(OneOfMine);
-
+private interface OneOfMine {}
+declare parents: com.bigboxco..* implements OneOfMine;
+pointcut oneOfMine(): this(OneOfMine);
....
If you want the more dynamic matching and are willing to pay for the
performance, then you should use the Java reflection API combined with
if. That would look something like:
+[source, java]
....
- pointcut oneOfMine(): this(Object) &&
- if(classMatches("com.bigboxco..*",
- thisJoinPoint.getTarget().getClass()));
-
- static boolean classMatches(String pattern, Class _class) {
- if (patternMatches(pattern, _class.getName())) return true;
- ...
- }
+pointcut oneOfMine(): this(Object) &&
+ if(classMatches("com.bigboxco..*",
+ thisJoinPoint.getTarget().getClass()));
+static boolean classMatches(String pattern, Class _class) {
+ if (patternMatches(pattern, _class.getName())) return true;
+ ...
+}
....
Note: wildcard type matching still works in all other PCD's that match
@@ -696,9 +695,9 @@ deprecated by the compiler, and will always return 0.
AspectJ 1.1 has a new declare form:
+[source, java]
....
- declare precedence ":" TypePatternList ";"
-
+declare precedence ":" TypePatternList ";"
....
This is used to declare advice ordering constraints on join points. For
@@ -707,9 +706,9 @@ their name should dominate all other aspects, and (2) the Logging aspect
(and any aspect that extends it) should dominate all non-security
aspects, can be expressed by:
+[source, java]
....
- declare precedence: *..*Security*, Logging+, *;
-
+declare precedence: *..*Security*, Logging+, *;
....
In the TypePatternList, the wildcard * means "any type not matched by
@@ -720,19 +719,19 @@ another type in the declare precedence".
It is an error for any aspect to be matched by more than one TypePattern
in a single declare precedence, so:
+[source, java]
....
- declare precedence: A, B, A ; // error
-
+declare precedence: A, B, A ; // error
....
However, multiple declare precedence forms may legally have this kind of
circularity. For example, each of these declare precedence is perfectly
legal:
+[source, java]
....
- declare precedence: B, A;
- declare precedence: A, B;
-
+declare precedence: B, A;
+declare precedence: A, B;
....
And a system in which both constraints are active may also be legal, so
@@ -743,33 +742,33 @@ idiom that can be used to enforce that A and B are strongly independent.
Consider the following library aspects:
+[source, java]
....
- abstract aspect Logging {
- abstract pointcut logged();
+abstract aspect Logging {
+ abstract pointcut logged();
- before(): logged() {
- System.err.println("thisJoinPoint: " + thisJoinPoint);
- }
- }
-
- aspect MyProfiling {
- abstract pointcut profiled();
+ before(): logged() {
+ System.err.println("thisJoinPoint: " + thisJoinPoint);
+ }
+}
- Object around(): profiled() {
- long beforeTime = System.currentTimeMillis();
- try {
- return proceed();
- } finally {
- long afterTime = System.currentTimeMillis();
- addToProfile(thisJoinPointStaticPart,
- afterTime - beforeTime);
- }
- }
- abstract void addToProfile(
- org.aspectj.JoinPoint.StaticPart jp,
- long elapsed);
- }
+aspect MyProfiling {
+ abstract pointcut profiled();
+ Object around(): profiled() {
+ long beforeTime = System.currentTimeMillis();
+ try {
+ return proceed();
+ } finally {
+ long afterTime = System.currentTimeMillis();
+ addToProfile(thisJoinPointStaticPart,
+ afterTime - beforeTime);
+ }
+ }
+ abstract void addToProfile(
+ org.aspectj.JoinPoint.StaticPart jp,
+ long elapsed);
+}
....
In order to use either aspect, they must be extended with concrete
@@ -780,9 +779,9 @@ with the concrete aspect MyProfiling) without adding a dominates clause
to Logging itself. In AspectJ 1.1, we can express that constraint with a
simple:
+[source, java]
....
- declare precedence: MyLogging, MyProfiling;
-
+declare precedence: MyLogging, MyProfiling;
....
===== Changing order of advice for sub-aspects
@@ -791,23 +790,23 @@ By default, advice in a sub-aspect has more precedence than advice in a
super-aspect. One use of the AspectJ 1.0 dominates form was to change
this precedence:
+[source, java]
....
- abstract aspect SuperA dominates SubA {
- pointcut foo(): ... ;
+abstract aspect SuperA dominates SubA {
+ pointcut foo(): ... ;
- before(): foo() {
- // in AspectJ 1.0, runs before the advice in SubA
- // because of the dominates clause
- }
- }
-
- aspect SubA extends SuperA {
- before(): foo() {
- // in AspectJ 1.0, runs after the advice in SuperA
- // because of the dominates clause
- }
- }
+ before(): foo() {
+ // in AspectJ 1.0, runs before the advice in SubA
+ // because of the dominates clause
+ }
+}
+aspect SubA extends SuperA {
+ before(): foo() {
+ // in AspectJ 1.0, runs after the advice in SuperA
+ // because of the dominates clause
+ }
+}
....
This no longer works in AspectJ 1.1, since declare precedence only
@@ -827,10 +826,10 @@ So, if you have your project separated into a gui module and a base
module, each of which is stored in a directory tree, you might use one
of
+[source, text]
....
- ajc -sourceroots /myProject/gui:/myProject/base
- ajc -sourceroots d:\myProject\gui;d:\myProject\base
-
+ajc -sourceroots /myProject/gui:/myProject/base
+ajc -sourceroots d:\myProject\gui;d:\myProject\base
....
This option may be used in conjunction with lst files, listing .java
@@ -848,10 +847,10 @@ Windows).
So, if MyTracing.java defines a trace aspect that you want to apply to
all the classes in myBase.jar and myGui.jar, you would use one of:
+[source, text]
....
- ajc -injars /bin/myBase.jar:/bin/myGui.jar MyTracing.java
- ajc -injars d:\bin\myBase.jar;d:\bin\myGui.jar MyTracing.java
-
+ajc -injars /bin/myBase.jar:/bin/myGui.jar MyTracing.java
+ajc -injars d:\bin\myBase.jar;d:\bin\myGui.jar MyTracing.java
....
The class files in the input jars must not have had advice woven into
@@ -869,9 +868,9 @@ files on the command line, and the -sourceroots option.
The -outjar option takes the name of a jar file into which the results
of the compilation should be put. For example:
+[source, text]
....
- ajc -injars myBase.jar MyTracing.java -outjar myTracedBase.jar
-
+ajc -injars myBase.jar MyTracing.java -outjar myTracedBase.jar
....
No meta information is placed in the output jar file.
@@ -920,17 +919,17 @@ The binary forms of this aspects will be untouched.
The 1.0 implementation of AspectJ, when given:
+[source, java]
....
- class MyRunnable implements Runnable {
- public void run() { ... }
- }
+class MyRunnable implements Runnable {
+ public void run() { /*...*/ }
+}
- aspect A {
- call(): (void run()) && target(MyRunnable) {
- // do something here
- }
+aspect A {
+ call(): (void run()) && target(MyRunnable) {
+ // do something here
}
-
+}
....
would cause A's advice to execute even when, say, java.lang.Thread
@@ -1117,14 +1116,14 @@ AspectJ 1.1 does not allow the inter-type definition of a zero-argument
constructor on a class with a visible default constructor. So this is no
longer allowed:
+[source, java]
....
- class C {}
-
- aspect A {
- C.new() {} // was allowed in 1.0.6
- // is a "multiple definitions" conflict in 1.1
- }
+class C {}
+aspect A {
+ C.new() {} // was allowed in 1.0.6
+ // is a "multiple definitions" conflict in 1.1
+}
....
In the Java Programming Language, a class defined without a constructor
@@ -1154,25 +1153,25 @@ The first two properties are important and are preserved in AspectJ 1.1,
but the third property is and was ludicrous, and was never properly
implemented (and never could be) in AspectJ 1.0.6. Consider:
+[source, java]
....
- interface Top0 {}
- interface Top1 {}
- interface I extends Top0, Top1 {}
- interface J extends Top1, Top0 {}
+interface Top0 {}
+interface Top1 {}
+interface I extends Top0, Top1 {}
+interface J extends Top1, Top0 {}
- class C implements I, J {}
- // I says Top0's inits must run before Top1's
- // J says Top1's inits must run before Top0's
+class C implements I, J {}
+// I says Top0's inits must run before Top1's
+// J says Top1's inits must run before Top0's
- aspect A {
- int Top0.i = foo("I'm in Top0");
- int Top1.i = foo("I'm in Top1");
- static int foo(String s) {
- System.out.println(s);
- return 37;
- }
+aspect A {
+ int Top0.i = foo("I'm in Top0");
+ int Top1.i = foo("I'm in Top1");
+ static int foo(String s) {
+ System.out.println(s);
+ return 37;
}
-
+}
....
This was simply a bug in the AspectJ specification. The correct third
@@ -1198,27 +1197,27 @@ not to return a value, but to simply assign a value.
Thus, programmers typically wanted to write something like:
+[source, java]
....
- void around(): set(int Foo.i) {
- if (theSetIsAllowed()) {
- proceed();
- }
+void around(): set(int Foo.i) {
+ if (theSetIsAllowed()) {
+ proceed();
}
-
+}
....
And were confused by it being a compile-time error. They weren't
confused for long, and soon adapted to writing:
+[source, java]
....
- int around(): set(int Foo.i) {
- if (theSetIsAllowed()) {
- return proceed();
- } else {
- return Foo.i;
- }
+int around(): set(int Foo.i) {
+ if (theSetIsAllowed()) {
+ return proceed();
+ } else {
+ return Foo.i;
}
-
+}
....
But there was definitely a short disconnect.
@@ -1267,6 +1266,7 @@ implementation.
In Java, the + operator sometimes results in StringBuffer objects being
created, appended to, and used to generate a new String. Thus,
+[source, java]
....
class Foo {
String makeEmphatic(String s) {
@@ -1277,6 +1277,7 @@ class Foo {
is approximately the same at runtime as
+[source, java]
....
class Foo {
String makeEmphatic(String s) {
@@ -1292,6 +1293,7 @@ discuss it), but in 1.1 we do.
This change is likely to affect highly wildcarded aspects, and can do so
in surprising ways. In particular:
+[source, java]
....
class A {
before(int i): call(* *(int)) && args(i) {
@@ -1303,6 +1305,7 @@ class A {
may result in a stack overflow error, since the argument to println is
really
+[source, java]
....
new StringBuffer("entering with ").append(i).toString()
....
@@ -1310,6 +1313,7 @@ new StringBuffer("entering with ").append(i).toString()
which has a call to StringBuffer.append(int). In such cases, it's worth
restricting your pointcut, with something like one of:
+[source, java]
....
call(* *(int)) && args(i) && !within(A)
call(* *(int)) && args(i) && !target(StringBuffer)
@@ -1320,6 +1324,7 @@ call(* *(int)) && args(i) && !target(StringBuffer)
Consider the following aspect
+[source, java]
....
public aspect SwingCalls {
@@ -1333,9 +1338,10 @@ public aspect SwingCalls {
And then consider the two statements
+[source, java]
....
- JFrame frame = new JFrame();
- frame.setTitle("Title");
+JFrame frame = new JFrame();
+frame.setTitle("Title");
....
According to the Java Language Specification version 2, the call to
diff --git a/docs/dist/doc/README-12.adoc b/docs/dist/doc/README-12.adoc
index 95775b45a..0b66b6556 100644
--- a/docs/dist/doc/README-12.adoc
+++ b/docs/dist/doc/README-12.adoc
@@ -139,21 +139,19 @@ returns false.
Consider a simple tracing aspect as follows:
+[source, java]
....
+public aspect Tracing {
- public aspect Tracing {
+ public static boolean enabled = false;
- public static boolean enabled = false;
+ pointcut toBeTraced() : execution(* *(..)) || execution(new(..));
- pointcut toBeTraced() : execution(* *(..)) || execution(new(..));
-
- before() : toBeTraced() && if(enabled) {
- Object[] args = thisJoinPoint.getArgs();
- // format args and print out entry trace record etc....
- }
+ before() : toBeTraced() && if(enabled) {
+ Object[] args = thisJoinPoint.getArgs();
+ // format args and print out entry trace record etc....
}
-
-
+}
....
The most important consideration is the system overhead when tracing is
@@ -189,20 +187,20 @@ were passed to the compiler. For example, an error message arising as a
result of a `declare error` statement might look as follows under
AspectJ 1.1.1:
+[source, text]
....
- BadClass.java:6 should not be calling bad methods
-
+BadClass.java:6 should not be calling bad methods
....
whereas in AspectJ 1.2 you will see:
+[source, text]
....
- BadClass.java:6 error should not be calling bad methods
- new C().bad();
- ^^^^^^^^^^^^^^
- method-call(void C.bad())
- see also: DeclareError.java:5
-
+BadClass.java:6 error should not be calling bad methods
+new C().bad();
+^^^^^^^^^^^^^^
+ method-call(void C.bad())
+ see also: DeclareError.java:5
....
There are four new things to note about this error message. Firstly,
@@ -220,13 +218,13 @@ When source code is not available, the messages show the binary input
source (class file or jar file) in which the error or warning was
detected:
+[source, text]
....
- BadClass.java:6 error should not be calling bad methods
- (no source information available)
- method-call(void C.bad())
- see also: C:\...\DeclareError.java:5
- see also: C:\...\bin-input.jar
-
+BadClass.java:6 error should not be calling bad methods
+(no source information available)
+ method-call(void C.bad())
+ see also: C:\...\DeclareError.java:5
+ see also: C:\...\bin-input.jar
....
This error message tells us that `BadClass.class` contained in a jar on
@@ -240,38 +238,36 @@ line 5 of the file `DeclareError.java`.
Consider the program:
+[source, java]
....
-
- 01 class A {
- 02 public void doIt() {...};
- 03 }
- 04
- 05 class B extends A {
- 06 public void doThisToo() {...};
- 07 }
- 08
- 09
- 10 public class CallsAandB {
- 11
- 12 public static void main(String[] args) {
- 13 B b = new B();
- 14 A bInDisguise = new B();
- 15
- 16 b.doIt(); // AspectJ 1.2 matches here
- 17 bInDisguise.doIt(); // this is never matched
- 18 }
- 19
- 20 }
- 21
- 22 aspect CallPCDMatchingExample {
- 23
- 24 before() : call(* B.doIt(..)) {
- 25 System.out.println("About to call B.doIt(...)");
- 26 }
- 27
- 28 }
-
-
+/*01*/ class A {
+/*02*/ public void doIt() {...};
+/*03*/ }
+/*04*/
+/*05*/ class B extends A {
+/*06*/ public void doThisToo() {...};
+/*07*/ }
+/*08*/
+/*09*/
+/*10*/ public class CallsAandB {
+/*11*/
+/*12*/ public static void main(String[] args) {
+/*13*/ B b = new B();
+/*14*/ A bInDisguise = new B();
+/*15*/
+/*16*/ b.doIt(); // AspectJ 1.2 matches here
+/*17*/ bInDisguise.doIt(); // this is never matched
+/*18*/ }
+/*19*/
+/*20*/ }
+/*21*/
+/*22*/ aspect CallPCDMatchingExample {
+/*23*/
+/*24*/ before() : call(* B.doIt(..)) {
+/*25*/ System.out.println("About to call B.doIt(...)");
+/*26*/ }
+/*27*/
+/*28*/ }
....
Because the static type of `bInDisguise` is `A` (line 14), the call on
@@ -287,19 +283,14 @@ designator does not match at a join point, and a user may have expected
it to. Compiling the above program using AspectJ 1.2 produces the
following compiler output:
+[source, text]
....
+CallsAandB.java:24 warning does not match because declaring type is A, if match desired use target(B) [Xlint:unmatchedSuperTypeInCall]
+before() : call(* B.doIt(..)) {
+ ^^^^^^^^^^^^^^^
+ see also: CallsAandB.java:17
-
- CallsAandB.java:24 warning does not match because declaring type is A, if match desired use target(B) [Xlint:unmatchedSuperTypeInCall]
- before() : call(* B.doIt(..)) {
- ^^^^^^^^^^^^^^^
- see also: CallsAandB.java:17
-
-
- 1 warning
-
-
-
+1 warning
....
The warning is telling us that the call pointcut associated with the
@@ -385,38 +376,36 @@ Consider again the following example program which illustrates the
differences in join point matching with the `call` pointcut designator
between 1.4 and 1.3 compliance levels.
+[source, java]
....
-
- 01 class A {
- 02 public void doIt() {...};
- 03 }
- 04
- 05 class B extends A {
- 06 public void doThisToo() {...};
- 07 }
- 08
- 09
- 10 public class CallsAandB {
- 11
- 12 public static void main(String[] args) {
- 13 B b = new B();
- 14 A bInDisguise = new B();
- 15
- 16 b.doIt(); // AspectJ 1.2 matches here
- 17 bInDisguise.doIt(); // this is never matched
- 18 }
- 19
- 20 }
- 21
- 22 aspect CallPCDMatchingExample {
- 23
- 24 before() : call(* B.doIt(..)) {
- 25 System.out.println("About to call B.doIt(...)");
- 26 }
- 27
- 28 }
-
-
+/*01*/ class A {
+/*02*/ public void doIt() {...};
+/*03*/ }
+/*04*/
+/*05*/ class B extends A {
+/*06*/ public void doThisToo() {...};
+/*07*/ }
+/*08*/
+/*09*/
+/*10*/ public class CallsAandB {
+/*11*/
+/*12*/ public static void main(String[] args) {
+/*13*/ B b = new B();
+/*14*/ A bInDisguise = new B();
+/*15*/
+/*16*/ b.doIt(); // AspectJ 1.2 matches here
+/*17*/ bInDisguise.doIt(); // this is never matched
+/*18*/ }
+/*19*/
+/*20*/ }
+/*21*/
+/*22*/ aspect CallPCDMatchingExample {
+/*23*/
+/*24*/ before() : call(* B.doIt(..)) {
+/*25*/ System.out.println("About to call B.doIt(...)");
+/*26*/ }
+/*27*/
+/*28*/ }
....
When this program is compiled with AspectJ 1.2 using the default
@@ -492,20 +481,21 @@ sample application that demonstrates these capabilities. Following the
instructions in the `README` file in that directory, running
"`aj tracing.ExampleMain`" with `ASPECTPATH` unset produces the output:
+[source, text]
....
- c1.perimeter() = 12.566370614359172
- c1.area() = 12.566370614359172
- s1.perimeter() = 4.0
- s1.area() = 1.0
- c2.distance(c1) = 4.242640687119285
- s1.distance(c1) = 2.23606797749979
- s1.toString(): Square side = 1.0 @ (1.0, 2.0)
-
+c1.perimeter() = 12.566370614359172
+c1.area() = 12.566370614359172
+s1.perimeter() = 4.0
+s1.area() = 1.0
+c2.distance(c1) = 4.242640687119285
+s1.distance(c1) = 2.23606797749979
+s1.toString(): Square side = 1.0 @ (1.0, 2.0)
....
If you set `ASPECTPATH` to include `../jars/tracingLib.jar`, and run
"`aj tracing.ExampleMain`" again, the output will be:
+[source, text]
....
--> tracing.TwoDShape(double, double)
<-- tracing.TwoDShape(double, double)
@@ -542,7 +532,6 @@ s1.area() = 1.0
<-- double tracing.TwoDShape.getY()
<-- double tracing.TwoDShape.distance(TwoDShape)
etc...
-
....
The scripts only support JDK 1.4 and above - attempting to use them with
diff --git a/docs/dist/doc/README-121.adoc b/docs/dist/doc/README-121.adoc
index 74d4b3030..fd082ebcb 100644
--- a/docs/dist/doc/README-121.adoc
+++ b/docs/dist/doc/README-121.adoc
@@ -34,17 +34,18 @@ option, or set showweaveinfo=true in the iajc ant task.
The following is an example of the messages produced when this option is
enabled:
+[source, text]
....
- C:\aspectj1.2.1\doc\examples\tjp>ajc -showWeaveInfo *.java
+C:\aspectj1.2.1\doc\examples\tjp>ajc -showWeaveInfo *.java
- Type 'tjp.Demo' (Demo.java:20) advised by around advice from 'tjp.GetInfo'
- (GetInfo.java:26) [RuntimeTest=true]
+Type 'tjp.Demo' (Demo.java:20) advised by around advice from 'tjp.GetInfo'
+(GetInfo.java:26) [RuntimeTest=true]
- Type 'tjp.Demo' (Demo.java:30) advised by around advice from 'tjp.GetInfo'
- (GetInfo.java:26) [RuntimeTest=true]
+Type 'tjp.Demo' (Demo.java:30) advised by around advice from 'tjp.GetInfo'
+(GetInfo.java:26) [RuntimeTest=true]
- Type 'tjp.Demo' (Demo.java:34) advised by around advice from 'tjp.GetInfo'
- (GetInfo.java:26) [RuntimeTest=true]
+Type 'tjp.Demo' (Demo.java:34) advised by around advice from 'tjp.GetInfo'
+(GetInfo.java:26) [RuntimeTest=true]
....
=== Dump Support
@@ -91,11 +92,11 @@ detecting this performance related bug and for piloting the fix.
String concatentation in declare error and warning statements is now
supported. For example, you can write:
+[source, java]
....
- declare warning : jdbcCall() && !inDataLayer()
- : "Please don't make calls to JDBC " +
- "outside of the data layer.";
-
+declare warning : jdbcCall() && !inDataLayer()
+ : "Please don't make calls to JDBC " +
+ "outside of the data layer.";
....
=== Load-time Weaving Support
diff --git a/docs/dist/doc/README-153.adoc b/docs/dist/doc/README-153.adoc
index 8b1c065f1..422b34447 100644
--- a/docs/dist/doc/README-153.adoc
+++ b/docs/dist/doc/README-153.adoc
@@ -14,8 +14,7 @@ Notable changes since the 1.5.2 release include: +
Until this release, the memory profile for AspectJ looked like this
(time is along the X axis, memory usage is the Y axis)
-``
-
+[source, text]
....
/\_
/ \_
@@ -31,8 +30,7 @@ discarding them once woven and dumped to disk. In 1.5.3 we don't compile
everything up front - we compile and weave files one at a time. Giving
us this profile:
-``
-
+[source, text]
....
/\ /\ /\
/ \/ \/ \
@@ -46,6 +44,7 @@ to compile a project. For example, I have a 1000file project, affected
by aspects at >750 join points. For given values of Xmx, here are the
times taken to compile it (on the command line) with AspectJ1.5.2:
+[source, text]
....
Xmx Time
512M 33seconds
@@ -58,6 +57,7 @@ The times gradually increase as the memory is reduced because the VM
starts to thrash in garbage collection. Here are the results for
AspectJ1.5.3:
+[source, text]
....
Xmx Time
512M 33s
@@ -106,8 +106,7 @@ Concrete aspects defined using aop.xml are now exposed for weaving.
It is now possible to ask an instance of a ptw aspect which type it is
'attached' to. The method:
-``
-
+[source, java]
....
String getWithinTypeName()
....
diff --git a/docs/dist/doc/README-160.adoc b/docs/dist/doc/README-160.adoc
index cba5ce076..d62985634 100644
--- a/docs/dist/doc/README-160.adoc
+++ b/docs/dist/doc/README-160.adoc
@@ -35,6 +35,7 @@ parentheses around the parameter types in a method signature determine
whether the annotations relate to the type of the parameter or the
parameter itself.
+[source, java]
....
execution(* *(@A *));
....
@@ -42,12 +43,14 @@ execution(* *(@A *));
- Execution of a method/ctor whose first parameter is of a type
annotated with @A.
+[source, java]
....
execution(* *(@A (*)));
....
- Execution of a method/ctor whose first parameter is annotated with @A
+[source, java]
....
execution(* *(@A (@B *)))
....
@@ -55,8 +58,9 @@ execution(* *(@A (@B *)))
- Execution of a method/ctor whose first parameter is annotated with @A
and is of a type annotated with @B. Example:
+[source, java]
....
------- Start of Test.java -----
+// ------ Start of Test.java -----
@interface A {}
@interface B {}
@@ -69,7 +73,11 @@ aspect X {
before(): execution(* *(@A (*))) {}
before(): execution(* *(@B (*))) {}
}
------- End of Test.java -----
+// ------ End of Test.java -----
+....
+
+[source, text]
+....
$ ajc -showWeaveInfo -1.6 Test.java
Join point 'method-execution(void C.foo(java.lang.String))' in Type 'C' (A.java:5) advised by before advice from 'X' (A.java:10)
@@ -78,9 +86,7 @@ Join point 'method-execution(void C.goo(java.lang.String))' in Type 'C' (A.java:
Join point 'method-execution(void C.goo(java.lang.String))' in Type 'C' (A.java:6) advised by before advice from 'X' (A.java:10)
....
-The first piece of advice matched both methods. The second only matched
-goo(). +
- +
+The first piece of advice matched both methods. The second only matched `goo()`.
==== Annotation Value Matching
@@ -93,13 +99,14 @@ has a particular value. Perhaps tracing has been turned on at the type
level and a few critical methods should not get traced. Here is some
code showing the use case:
+[source, java]
....
enum TraceLevel { NONE, LEVEL1, LEVEL2, LEVEL3 }
@interface Trace {
TraceLevel value() default TraceLevel.LEVEL1;
}
-
+
aspect X {
// Advise all methods marked @Trace except those with a tracelevel of none
before(): execution(@Trace !@Trace(TraceLevel.NONE) * *(..)) {
diff --git a/docs/dist/doc/README-161.adoc b/docs/dist/doc/README-161.adoc
index 2cea859bb..d4ef20cf4 100644
--- a/docs/dist/doc/README-161.adoc
+++ b/docs/dist/doc/README-161.adoc
@@ -146,8 +146,7 @@ If only binding an annotation at a method-execution join point in order
to access an *enum value* within it, there is a more optimal syntax that
can be used to produce faster code. Given this setup:
-``
-
+[source, java]
....
enum Colour { RED,GREEN,BLUE;}
@@ -159,6 +158,7 @@ public void colouredMethod() { }
Current syntax:
+[source, java]
....
before(ColouredAnnotation anno): execution(* *(..)) && @annotation(anno) {
printTheColour(anno.value());
@@ -167,12 +167,9 @@ before(ColouredAnnotation anno): execution(* *(..)) && @annotation(anno) {
New optional syntax:
-``
-
+[source, java]
....
before(Colour col): execution(* *(..)) && @annotation(ColouredAnnotation(col)) {
printTheColour(col);
}
....
-
-'''''
diff --git a/docs/dist/doc/README-1610.adoc b/docs/dist/doc/README-1610.adoc
index faf6b85d6..73d3dab90 100644
--- a/docs/dist/doc/README-1610.adoc
+++ b/docs/dist/doc/README-1610.adoc
@@ -23,6 +23,7 @@ project properties in eclipse and in the AspectJ Compiler section,
scroll down to 'Other' and in the non-standard compiler options setting,
specify:
+[source, text]
....
-Xset:minimalModel=true,typeDemotion=true
....
diff --git a/docs/dist/doc/README-1611.adoc b/docs/dist/doc/README-1611.adoc
index e240e36f4..d88609580 100644
--- a/docs/dist/doc/README-1611.adoc
+++ b/docs/dist/doc/README-1611.adoc
@@ -74,6 +74,7 @@ annotations, or modify existing annotations by changing their values.
1.6.11 includes a new piece of syntax that we are thinking might be
appropriate for one of these scenarios. 1.6.11 supports this:
+[source, java]
....
declare @field: int Foo.i: -@Anno;
....
@@ -89,6 +90,7 @@ but the inability to use it with binary weaving greatly reduced the
usefulness. Fixes have gone into 1.6.11 to support binary weaving. What
do we mean by intertype innertypes? Here is an example:
+[source, java]
....
class Foo {
public void m() {
diff --git a/docs/dist/doc/README-1612.adoc b/docs/dist/doc/README-1612.adoc
index d69061257..78a90829a 100644
--- a/docs/dist/doc/README-1612.adoc
+++ b/docs/dist/doc/README-1612.adoc
@@ -43,13 +43,14 @@ added and for some cases there can be no need for that abstract aspect.
This is a work in progress but now you can write this in the aop.xml:
+[source, xml]
....
<concrete-aspect name="MyAspect">
<before pointcut="execution(* Hello.say2(..)) AND args(message)"
- invokeClass="SomeRegularJavaClass"
+ invokeClass="SomeRegularJavaClass"
invokeMethod="someMethod(JoinPoint tjp, java.lang.String message)"/>
<after pointcut="execution(* Hello.say2(..)) AND args(message)"
- invokeClass="SomeRegularJavaClass"
+ invokeClass="SomeRegularJavaClass"
invokeMethod="someOtherMethod(JoinPoint tjp, java.lang.String message)"/>
</concrete-aspect>
@@ -58,7 +59,7 @@ public class SomeRegularJavaClass {
public static void someMethod(org.aspectj.lang.JoinPoint tjp, String s) {
System.out.println("in advice4: s="+s+" at "+tjp);
}
-
+
public static void someOtherMethod(org.aspectj.lang.JoinPoint tjp, String s) {
System.out.println("in advice5: s="+s+" at "+tjp);
}
@@ -101,8 +102,9 @@ get started!
There is now a new well known name that you can use in the if clauses in
your aspects. thisAspectInstance provides access to the aspect instance.
-Here is an example: ``
+Here is an example:
+[source, java]
....
aspect X {
boolean doit() {
@@ -116,10 +118,11 @@ aspect X {
}
....
-Now why not just use X.aspectOf() instead of thisAspectInstance? Well
-thisAspectInstance is quite useful when working with abstract/concrete
-aspects: ``
+Now why not just use `X.aspectOf()` instead of `thisAspectInstance`? Well,
+`thisAspectInstance` is quite useful when working with abstract/concrete
+aspects:
+[source, java]
....
abstract aspect X {
abstract pointcut p();
@@ -185,6 +188,7 @@ supports Java7 language constructs - that will happen after Eclipse
It is now possible to specify synthetic in pointcuts:
+[source, java]
....
pointcut p(): execution(!synthetic * *(..));
....
@@ -210,6 +214,7 @@ use when you want to match upon the existence of an annotation but you
don't need the annotation, you just need a value from it. This code
snippet shows an example:
+[source, java]
....
@interface SomeAnnotation {
int i();
@@ -227,6 +232,7 @@ binding too. Suppose the annotation had multiple int values, how would
we select which int to bind? AspectJ will now use the name (if it can)
to select the right value:
+[source, java]
....
@interface SomeAnnotation {
int mods();
diff --git a/docs/dist/doc/README-164.adoc b/docs/dist/doc/README-164.adoc
index b1de0e9b0..548cb086e 100644
--- a/docs/dist/doc/README-164.adoc
+++ b/docs/dist/doc/README-164.adoc
@@ -27,8 +27,7 @@ the full build times in AJDT:
AJDT 1.6.3 (uses AspectJ 1.6.3)
-``
-
+[source, text]
....
21352ms
21597ms
@@ -37,8 +36,7 @@ AJDT 1.6.3 (uses AspectJ 1.6.3)
AJDT 1.6.5dev builds (use AspectJ 1.6.4)
-``
-
+[source, text]
....
19811ms
19802ms
@@ -70,8 +68,7 @@ building code, weaving code.
Initially this is using AJDT 1.6.2 (which embeds AspectJ 1.6.3):
-``
-
+[source, text]
....
Type of change: adding a new method to a type
Project build times (first one is the compile of our change, the rest are for downstream projects):
@@ -88,8 +85,7 @@ Summary: Total time spent in the compiler for that change: 1597ms
Now with AspectJ 1.6.5 dev builds (which embed AspectJ 1.6.4):
-``
-
+[source, text]
....
Type of change: adding a new method to a type
Project build times (first one is the compile of our change, the rest are for downstream projects):
@@ -127,8 +123,9 @@ http://andrewclement.blogspot.com/2009/02/aspectj-fixing-reverse-cascade-errors.
*Optimizing support for maintaining per join point state*
The traditional way to maintain state on a per join point basis involves
-using the JoinPoint.StaticPart as a key into a map: ``
+using the JoinPoint.StaticPart as a key into a map:
+[source, java]
....
aspect X pertypewithin(*) {
Map<JoinPoint.StaticPart,Timer> timerMap = ...
@@ -149,8 +146,7 @@ points within a target type are unique (and start from 0) - they are
ideal for array lookups. So using this the above aspect can be
rewritten:
-``
-
+[source, java]
....
aspect X pertypewithin(*) {
Timer[] timerArray = ...
@@ -189,17 +185,16 @@ target instance.
The @DeclareMixin annotation is attached to a factory method which
returns instances of the delegate. Here is a basic example:
-``
-
+[source, java]
....
- // The factory method that can build the delegate instance is annotated with @DeclareMixin.
- // The annotation value defines the type pattern for targets of the mixin.
- // The parameter is the object for which a delegate is being constructed.
- // The interface that will be mixed in is the return value of the factory method.
- @DeclareMixin("org.xyz..*")
- public static SomeInterface createDelegate(Object instance) {
- return new SomeImplementation(instance);
- }
+// The factory method that can build the delegate instance is annotated with @DeclareMixin.
+// The annotation value defines the type pattern for targets of the mixin.
+// The parameter is the object for which a delegate is being constructed.
+// The interface that will be mixed in is the return value of the factory method.
+@DeclareMixin("org.xyz..*")
+public static SomeInterface createDelegate(Object instance) {
+ return new SomeImplementation(instance);
+}
....
More examples are
@@ -248,5 +243,3 @@ weaver. Although the type map uses Weak/Soft references to try and
better control how it uses memory, the JVM policies for managing these
references vary wildly and so some work needs to be done to allow for
these differences.
-
-'''''
diff --git a/docs/dist/doc/README-167.adoc b/docs/dist/doc/README-167.adoc
index 66476f8cc..5a2a9ffcf 100644
--- a/docs/dist/doc/README-167.adoc
+++ b/docs/dist/doc/README-167.adoc
@@ -18,6 +18,7 @@ pointcut matching]. Basically by turning on the options '-timers
-verbose' on the command line (or via Ant), output will be produced that
looks a little like this:
+[source, text]
....
Pointcut matching cost (total=6532ms for 675000 joinpoint match calls):
Time:482ms (jps:#168585) matching against
@@ -102,8 +103,7 @@ that actually runs? One user, Oliver Hoff, raised a query on the
performance of annotation binding. His case uncovered an old TODO left
in the code a few years ago:
-``
-
+[source, text]
....
// OPTIMIZE cache result of getDeclaredMethod and getAnnotation?
....
@@ -121,29 +121,28 @@ value at an execution join point in different ways. The three scenarios
look like this (where the annotation type is 'Marker' and it has a
String value field called 'message'):
-``
-
+[source, java]
....
- // CaseOne: annotation value fetching is done in the advice:
- pointcut adviceRetrievesAnnotation(): execution(@Marker * runOne(..));
- before(): adviceRetrievesAnnotation() {
- Marker marker = (Marker) ((MethodSignature)
- thisJoinPointStaticPart.getSignature()).getMethod().getAnnotation(Marker.class);
- String s = marker.message();
- }
-
- // CaseTwo: annotation binding is done in the pointcut, advice retrieves message
- pointcut pointcutBindsAnnotation(Marker l): execution(@Marker * runTwo(..)) && @annotation(l);
- before(Marker l): pointcutBindsAnnotation(l) {
- String s = l.message();
- }
-
- // CaseThree: annotation binding directly targets the message value in the annotation
- pointcut pointcutBindsAnnotationValue(String msg):
- execution(@Marker * runThree(..)) && @annotation(Marker(msg));
- before(String s): pointcutBindsAnnotationValue(s) {
- // already got the string
- }
+// CaseOne: annotation value fetching is done in the advice:
+pointcut adviceRetrievesAnnotation(): execution(@Marker * runOne(..));
+before(): adviceRetrievesAnnotation() {
+ Marker marker = (Marker) ((MethodSignature)
+ thisJoinPointStaticPart.getSignature()).getMethod().getAnnotation(Marker.class);
+ String s = marker.message();
+}
+
+// CaseTwo: annotation binding is done in the pointcut, advice retrieves message
+pointcut pointcutBindsAnnotation(Marker l): execution(@Marker * runTwo(..)) && @annotation(l);
+before(Marker l): pointcutBindsAnnotation(l) {
+ String s = l.message();
+}
+
+// CaseThree: annotation binding directly targets the message value in the annotation
+pointcut pointcutBindsAnnotationValue(String msg):
+ execution(@Marker * runThree(..)) && @annotation(Marker(msg));
+before(String s): pointcutBindsAnnotationValue(s) {
+ // already got the string
+}
....
Before 1.6.7, case 2 was slower than case 1 and case 3 wasn't supported
@@ -157,8 +156,7 @@ stress the AspectJ binding code. For the benchmark numbers the join
points advised by those advice were invoked 1,000,000 times. AspectJ
1.6.7:
-``
-
+[source, text]
....
Manually fetching annotation with getAnnotation(): 645ms
Binding annotation with @annotation(Marker): 445ms (was >20 *seconds* for 1.6.6, due to an extra reflection call)
diff --git a/docs/dist/doc/README-168.adoc b/docs/dist/doc/README-168.adoc
index eee958509..0a8e3cbb8 100644
--- a/docs/dist/doc/README-168.adoc
+++ b/docs/dist/doc/README-168.adoc
@@ -25,12 +25,11 @@ that is not
These three meet that spec:
-``
-
+[source, xml]
....
- <include within="*"/>
- <include within="@Foo *"/>
- <exclude within="*Funk*y*"/>
+<include within="*"/>
+<include within="@Foo *"/>
+<exclude within="*Funk*y*"/>
....
The include="*" can be optimized. The include="@Foo *" is not optimized.
@@ -51,22 +50,21 @@ more frequently.
The stack trace when this is hit looks like:
-``
-
+[source, text]
....
- ...
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
- at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
- ...
+...
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:427)
+at org.aspectj.weaver.ReferenceType.isAssignableFrom(ReferenceType.java:393)
+...
....
The weaver has changed over the 1.5 and 1.6 releases and is now reaching
diff --git a/docs/dist/doc/README-169.adoc b/docs/dist/doc/README-169.adoc
index 1df44489f..4921f23d4 100644
--- a/docs/dist/doc/README-169.adoc
+++ b/docs/dist/doc/README-169.adoc
@@ -14,6 +14,7 @@ declare annotation constructs that take a member signature. For example,
if you wanted to attach an annotation to all your getter like methods,
you needed two constructs
+[source, java]
....
declare @method: * is*(): @FooBar;
declare @method: * get*(): @FooBar;
@@ -22,6 +23,7 @@ declare @method: * get*(): @FooBar;
Now AspectJ allows compound patterns for declare
@method/@constructor/@field.
+[source, java]
....
declare @method: (* is*()) || (* get*()): @FooBar;
....
@@ -32,6 +34,7 @@ It is now possible to ITD member types. The syntax is as would be
expected. This example introduces a new member type called Inner into
type Foo:
+[source, java]
....
public class Foo {
public static void main(String[] args) {
@@ -71,10 +74,9 @@ within it to switch-off if there is nothing for them to do.
Here is an example, 'AspectA' will switch itself off if the type
'a.b.c.Anno' cannot be found:
-``
-
+[source, xml]
....
- <aspect name="AspectA" requires="a.b.c.Anno"/>
+<aspect name="AspectA" requires="a.b.c.Anno"/>
....
==== Reduction in class file sizes: https://bugs.eclipse.org/bugs/show_bug.cgi?id=312839[312839]
@@ -130,8 +132,7 @@ the pointcuts defined in the original aspect.
Here is an example:
-``
-
+[source, xml]
....
<aspectj>
<aspects>
@@ -154,8 +155,7 @@ specifies that Y should in fact only be applied to com.foo..* types.
It is now possible to use joinpoint context in the messages attached to
declare warning and declare error constructs. Some examples:
-``
-
+[source, java]
....
declare warning: execution(* A.m(..)): "joinpoint is {joinpoint}";
declare warning: execution(* A.m(..)): "joinpoint kind is '{joinpoint.kind}'";
@@ -178,8 +178,7 @@ the message. Please raise an enhancement request if you need other keys
It is now possible to use a type pattern with declare warning and
declare error. For example:
-``
-
+[source, java]
....
declare warning: I+ && !hasfield(int i): "Implementations of I are expected to have a int field called i";
....
@@ -190,8 +189,7 @@ This is the ability to narrow the types of interest so that interfaces
can be ignored, or inner types, or classes or aspects. There is now a
new is() construct that enables this:
-``
-
+[source, java]
....
execution(* (!is(InnerType)).m(..)) {}
!within(* && is(InnerType)) {}
@@ -202,8 +200,9 @@ InnerType, AnonymousType, EnumType, AnonymousType.
Note: It is important to understand that "!within(is(InnerType))" and
"within(!is(InnerType))" are not the same. The latter one is unlikely to
-be what you want to use. For example here: ``
+be what you want to use. For example here:
+[source, java]
....
class Boo {
void foo() {}
@@ -223,8 +222,7 @@ result of that match will be negated.
Some users always expect this:
-``
-
+[source, java]
....
class C {
}
@@ -248,8 +246,7 @@ produce slightly different output.
Here is the output of javap when that is built with 1.6.8:
-``
-
+[source, java]
....
class C extends java.lang.Object{
public int ajc$interField$X$someField;
@@ -259,8 +256,7 @@ class C extends java.lang.Object{
Here is the output of javap when that is built with 1.6.9:
-``
-
+[source, java]
....
class C extends java.lang.Object{
private int someField;
@@ -284,8 +280,7 @@ and if you browse to it you will see it currently contains 1.6.9 dev
builds under the name 1.6.9.BUILD-SNAPSHOT. The repo is added with this
magic:
-``
-
+[source, xml]
....
<repository>
<id>maven.springframework.org</id>
diff --git a/docs/dist/doc/README-170.adoc b/docs/dist/doc/README-170.adoc
index de0248de7..b76f56139 100644
--- a/docs/dist/doc/README-170.adoc
+++ b/docs/dist/doc/README-170.adoc
@@ -36,6 +36,7 @@ start of a system using LTW and then reuses that woven bytecode on
subsequent starts - this saves weaving time and also memory consumption.
To activate it, use the following system properties:
+[source, text]
....
-Daj.weaving.cache.enabled=true
-Daj.weaving.cache.dir=/tmp/aspectj-cache/
@@ -51,8 +52,9 @@ Eclipse compiler.
It means that you can now use the new Java 7 language constructs in your
programs:
-- Diamond operator in advice: ``
+- Diamond operator in advice:
+[source, java]
....
aspect Foo {
before(): execution(* *(..)) {
@@ -61,58 +63,63 @@ aspect Foo {
}
....
-- Diamond operator in ITD: ``
+- Diamond operator in ITD:
+[source, java]
....
public List DiamondITD.ls = new ArrayList<>();
....
-- Underscore literals and binary literals in advice: ``
+- Underscore literals and binary literals in advice:
+[source, java]
....
- before(): execution(* *(..)) {
- int onemill = 1_000_000;
- int four =0b100;
- }
+before(): execution(* *(..)) {
+ int onemill = 1_000_000;
+ int four =0b100;
+}
....
- Multi-catch:``
+[source, java]
....
before(): execution(* main(..)) {
- try {
- foo("abc");
- } catch (ExceptionA | ExceptionB ex) {
- bar(ex);
- }
+ try {
+ foo("abc");
+ } catch (ExceptionA | ExceptionB ex) {
+ bar(ex);
+ }
}
....
- String switch:``
+[source, java]
....
- before(String s): execution(* *(..)) && args(s) {
- switch(s) {
- case "quux":
- foo();
- break;
- case "bar":
- foo();
- break;
- default:
- foo();
- break;
- }
- }
+before(String s): execution(* *(..)) && args(s) {
+ switch(s) {
+ case "quux":
+ foo();
+ break;
+ case "bar":
+ foo();
+ break;
+ default:
+ foo();
+ break;
+ }
+}
....
- Try with resources:``
+[source, java]
....
- try (
- InputStream in = new FileInputStream(src);
- OutputStream out = new FileOutputStream(dest))
- {
- // code
- }
+try (
+ InputStream in = new FileInputStream(src);
+ OutputStream out = new FileOutputStream(dest))
+{
+ // code
+}
....
diff --git a/docs/dist/doc/README-174.adoc b/docs/dist/doc/README-174.adoc
index 7b4cbb54c..3b55b4a43 100644
--- a/docs/dist/doc/README-174.adoc
+++ b/docs/dist/doc/README-174.adoc
@@ -18,6 +18,7 @@ JVM where JMX is turned on
(https://bugs.eclipse.org/bugs/show_bug.cgi?id=420210[420210]) The new
keys are:
+
+[source, java]
....
joinpoint.enclosingclass // Bar
joinpoint.enclosingmember // void Bar.foo(String)
@@ -29,6 +30,7 @@ All keys are case insensitive.
needing to supply a file
(https://bugs.eclipse.org/bugs/show_bug.cgi?id=419279[419279])
+
+[source, text]
....
ajc -Xlint:adviceDidNotMatch=error,noGuardForLazyTjp=ignore Foo.java
....
diff --git a/docs/dist/doc/README-180.adoc b/docs/dist/doc/README-180.adoc
index fe988aa5a..115de3d6d 100644
--- a/docs/dist/doc/README-180.adoc
+++ b/docs/dist/doc/README-180.adoc
@@ -21,8 +21,9 @@ patch on top of Eclipse 4.3.2).
Here is a sample AspectJ8 program:
+[source, java]
....
-=== 8< ==== C.java ==== 8< ===
+// === 8< ==== C.java ==== 8< ===
import java.util.Arrays;
interface I {
@@ -67,5 +68,5 @@ class MyClass {
return args;
}
}
-=== 8< ==== C.java ==== 8< ===
+// === 8< ==== C.java ==== 8< ===
....
diff --git a/docs/dist/doc/README-182.adoc b/docs/dist/doc/README-182.adoc
index 45215367d..28fa7b2da 100644
--- a/docs/dist/doc/README-182.adoc
+++ b/docs/dist/doc/README-182.adoc
@@ -35,8 +35,7 @@ Here is a short example, a very basic annotation and application:
===== Marker.java
-``
-
+[source, java]
....
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
@@ -47,8 +46,7 @@ public @interface Marker { }
===== Code.java
-``
-
+[source, java]
....
public class Code {
@@ -60,13 +58,13 @@ public class Code {
}
public void moo() {}
-
+
@Marker
public void boo() {}
-
+
@Marker
public void too() {}
-
+
public void woo() {}
}
....
@@ -78,8 +76,7 @@ contrived demo!)
===== DemoProcessor.java
-``
-
+[source, java]
....
import java.io.*;
import javax.tools.*;
@@ -90,7 +87,7 @@ import javax.lang.model.element.*;
@SupportedAnnotationTypes(value= {"*"})
@SupportedSourceVersion(SourceVersion.RELEASE_6)
-public class DemoProcessor extends AbstractProcessor {
+public class DemoProcessor extends AbstractProcessor {
private Filer filer;
@@ -106,7 +103,7 @@ public class DemoProcessor extends AbstractProcessor {
if (element.getKind() == ElementKind.METHOD) {
// For any methods we find, create an aspect:
String methodName = element.getSimpleName().toString();
- String aspectText =
+ String aspectText =
"public aspect Advise_"+methodName+" {\n"+
" before(): execution(* "+methodName+"(..)) {\n"+
" System.out.println(\""+methodName+" running\");\n"+
@@ -131,22 +128,19 @@ public class DemoProcessor extends AbstractProcessor {
With those sources, we compile the processor:
-``
-
+[source, text]
....
ajc -1.6 DemoProcessor.java Marker.java
....
Now compile the code with the processor specified:
-``
-
+[source, text]
....
ajc -1.6 -processor DemoProcessor -showWeaveInfo Code.java Marker.java
....
-``
-
+[source, text]
....
Generated aspect to advise too
Generated aspect to advise boo
@@ -159,8 +153,7 @@ the code being compiled immediately.
Finally we can run it:
-``
-
+[source, text]
....
java Code
boo running
diff --git a/docs/dist/doc/README-183.adoc b/docs/dist/doc/README-183.adoc
index 95425e392..8c615ef84 100644
--- a/docs/dist/doc/README-183.adoc
+++ b/docs/dist/doc/README-183.adoc
@@ -35,6 +35,7 @@ extraneous dependencies to an applications build classpath.
Example:
+[source, java]
....
import org.aspectj.lang.annotation.*;
@@ -63,6 +64,7 @@ appears to come up when the aspect is non-optimal anyway and hitting
preinitialization was never really intended by the pointcut writer. For
example:
+[source, java]
....
execution(* foo(..)) && cflow(within(Bar))
....
@@ -72,12 +74,14 @@ joinpoints, many of which the user probably didn't mean to. It feels
like we actually need a warning to indicate the pointcut is probably
suboptimal. What the user probably meant was something more like this:
+[source, java]
....
execution(* foo(..)) && cflow(execution(* Bar.*(..))
....
or
+[source, java]
....
execution(* foo(..)) && cflow(within(Bar) && execution(* *(..)))
....
diff --git a/docs/dist/doc/README-187.adoc b/docs/dist/doc/README-187.adoc
index de61a362b..bcc5f75cc 100644
--- a/docs/dist/doc/README-187.adoc
+++ b/docs/dist/doc/README-187.adoc
@@ -25,8 +25,7 @@ will not be woven.
Here is a simple aspect:
-``
-
+[source, java]
....
public aspect Azpect {
before(): execution(* *(..)) {
@@ -37,8 +36,7 @@ public aspect Azpect {
Compiled via:
-``
-
+[source, text]
....
ajc -1.8 Azpect.java -outxml
....
@@ -48,8 +46,7 @@ META-INF/aop-ajc.xml.
I then have this sample application (same directory):
-``
-
+[source, java]
....
import java.lang.management.ManagementFactory;
import org.aspectj.weaver.loadtime.Agent;
@@ -96,8 +93,7 @@ public class Application {
And this Sample class:
-``
-
+[source, java]
....
public class Sample {
public void doSomething() {
@@ -116,8 +112,7 @@ JDK tools.jar on your classpath*.
Once compiled we can run it:
-``
-
+[source, text]
....
java -DAGENT_PATH=<path-to>/aspectjweaver.jar Application
....
diff --git a/docs/dist/doc/README-190.adoc b/docs/dist/doc/README-190.adoc
index 3b1f27784..323573146 100644
--- a/docs/dist/doc/README-190.adoc
+++ b/docs/dist/doc/README-190.adoc
@@ -41,6 +41,7 @@ In anticipation of not all build plugins supporting that
-Xajruntimetarget option, you can now specify these kinds of option in
the ASPECTJ_OPTS environment variable. Set that in your environment:
+[source, text]
....
export ASPECTJ_OPTS="-Xajruntimetarget:1.9"
....
@@ -58,17 +59,18 @@ useful with Java9 which includes a number of module related commands.
For example, here is an iajc usage with compilerArg that is passing
--add-modules java.xml.bind:
+[source, xml]
....
- <iajc destdir="bin" failonerror="true"
- showWeaveInfo="true" source="1.9" target="1.9"
- debug="true" fork="true" maxmem="256m">
- <compilerArg value="--add-modules"/>
- <compilerArg value="java.xml.bind"/>
- <src path="src" />
- <classpath>
- <pathelement location="${aspectj.home}/lib/aspectjrt.jar"/>
- </classpath>
- </iajc>
+<iajc destdir="bin" failonerror="true"
+ showWeaveInfo="true" source="1.9" target="1.9"
+ debug="true" fork="true" maxmem="256m">
+ <compilerArg value="--add-modules"/>
+ <compilerArg value="java.xml.bind"/>
+ <src path="src" />
+ <classpath>
+ <pathelement location="${aspectj.home}/lib/aspectjrt.jar"/>
+ </classpath>
+</iajc>
....
1.9.0.RC4 available 21-Feb-2018
@@ -103,6 +105,7 @@ AspectJ can now be used with the new module system available in Java9.
The key jars in AspectJ have been given automatic module names. The
automatic module name is org.aspectj.runtime for the aspectjrt module:
+[source, text]
....
$ java --module-path <pathto>/lib/aspectjrt.jar --list-modules | grep aspectj
@@ -112,6 +115,7 @@ org.aspectj.runtime file:///<pathto>/lib/aspectjrt.jar automatic
And similarly org.aspectj.weaver and org.aspectj.tools for aspectjweaver
and aspectjtools respectively:
+[source, text]
....
$ java --module-path <pathto>/lib/aspectjweaver.jar --describe-module org.aspectj.weaver
@@ -137,6 +141,7 @@ contains org.aspectj.asm.internal
AspectJ understands module-info.java source files and building modules
that include aspects. Here is an example:
+[source, java]
....
module-info.java
@@ -170,6 +175,7 @@ public aspect Azpect {
We can now build those into a module:
+[source, text]
....
$ ajc -1.9 module-info.java otherpkg/Azpect.java pkg/Demo.java -outjar demo.jar
@@ -182,12 +188,14 @@ Wait, that failed! Yes, aspectjrt.jar (which includes the required
org.aspectj.weaver module) wasn't supplied. We need to pass it on the
module-path:
+[source, text]
....
$ ajc -1.9 --module-path <pathto>/aspectjrt.jar module-info.java otherpkg/Azpect.java pkg/Demo.java -outjar demo.jar
....
Now we have a demo module we can run:
+[source, text]
....
$ java --module-path <pathto>/aspectjrt.jar:demo.jar --module demo/pkg.Demo
@@ -206,8 +214,9 @@ A module is really just a jar with a module-info descriptor. As such you
can simply pass a module on the inpath and binary weave it with other
aspects. Take the module we built above, let's weave into it again:
+[source, java]
....
-extra/AnotherAzpect.java
+// extra/AnotherAzpect.java
package extra;
@@ -218,6 +227,7 @@ public aspect AnotherAzpect {
}
....
+[source, text]
....
$ ajc -inpath demo.jar AnotherAzpect.java -outjar newdemo.jar
....
@@ -231,6 +241,7 @@ Because the new jar produced includes the compiled aspect, the
module-info specification inside is still correct, so we can run it
exactly as before:
+[source, text]
....
$ java --module-path ~/installs/aspectj190rc1/lib/aspectjrt.jar:newdemo.jar --module demo/pkg.Demo
@@ -239,9 +250,6 @@ AnotherAzpect running
Demo running
....
- +
- +
-
=== Faster Spring AOP
Dave Syer recently created a series of benchmarks for checking the speed
@@ -250,6 +258,7 @@ of Spring-AspectJ: https://github.com/dsyer/spring-boot-aspectj
Here we can see the numbers for AspectJ 1.8.11 (on an older Macbook
Pro):
+[source, text]
....
Benchmark (scale) Mode Cnt Score Error Units
StartupBenchmark.ltw N/A avgt 10 2.553 ~ 0.030 s/op
@@ -295,6 +304,7 @@ primary change is factoring in the annotation type.
What difference does that make? AspectJ 1.9.0.RC1:
+[source, text]
....
Benchmark (scale) Mode Cnt Score Error Units
StartupBenchmark.ltw N/A avgt 10 2.568 ~ 0.035 s/op
diff --git a/docs/dist/doc/README-191.adoc b/docs/dist/doc/README-191.adoc
index acab550c3..bba435893 100644
--- a/docs/dist/doc/README-191.adoc
+++ b/docs/dist/doc/README-191.adoc
@@ -14,6 +14,7 @@ AspectJ has updated to a recent JDT compiler version (commit
This means you can use the 'var' support. A simple example of combining
var with an aspect:
+[source, java]
....
public class Code3 {
public static void main(String []argv) {
diff --git a/docs/dist/doc/README-193.adoc b/docs/dist/doc/README-193.adoc
index a75724c2c..22824b66b 100644
--- a/docs/dist/doc/README-193.adoc
+++ b/docs/dist/doc/README-193.adoc
@@ -10,8 +10,9 @@ expression syntax, but you must activate support for that via an
--enable-preview flag when using the compiler and attempting to run the
resultant classes: Here is Switch3.java:
+[source, java]
....
-=========8<=========
+// =========8<=========
public class Switch3 {
public static void main(String[] argv) {
System.out.println(one(Color.R));
@@ -29,7 +30,7 @@ public class Switch3 {
};
return result;
}
-
+
public static final int foo(int i) {
return i+1;
}
@@ -44,11 +45,12 @@ aspect X {
return proceed()*3;
}
}
-=========8<=========
+// =========8<=========
....
Compile it with:
+[source, text]
....
$ ajc --enable-preview -showWeaveInfo -12 Switch3.java
@@ -63,6 +65,7 @@ Join point 'method-call(int Switch3.foo(int))' in Type 'Switch3' (Switch3.java:1
Now run it:
+[source, text]
....
$ java --enable-preview Switch3
3
diff --git a/docs/dist/doc/README-195.adoc b/docs/dist/doc/README-195.adoc
index 2af7e42a7..36a157c53 100644
--- a/docs/dist/doc/README-195.adoc
+++ b/docs/dist/doc/README-195.adoc
@@ -12,8 +12,9 @@ must activate support for that via an --enable-preview flag when using
the compiler and attempting to run the resultant classes: Here is
Code.java:
+[source, java]
....
-=======8<=========
+// =======8<=========
public class Code {
public static void main(String[] argv) {
}
@@ -33,17 +34,19 @@ lines
}
}
-=========8<=========
+// =========8<=========
....
Compile it with:
+[source, text]
....
$ ajc --enable-preview -13 Code.java
....
Now run it:
+[source, text]
....
$ java --enable-preview Code
This
diff --git a/docs/dist/doc/README-196.adoc b/docs/dist/doc/README-196.adoc
index 536cd4ec9..35e7ab2d3 100644
--- a/docs/dist/doc/README-196.adoc
+++ b/docs/dist/doc/README-196.adoc
@@ -11,12 +11,13 @@ AspectJ 1.9.6 supports Java14. Java14 introduces records, but you must
activate support for that via an --enable-preview flag when using the
compiler and attempting to run the resultant classes: Here is Code.java:
+[source, java]
....
-=======8<=========
+// =======8<=========
public record Person(String firstName, String lastName, int age) {}
-=======8<=========
+// =======8<=========
-=======8<=========
+// =======8<=========
public class UsingPersonRecord {
public static void main(String[] argv) {
Person p = new Person("A","B",99);
@@ -24,25 +25,27 @@ public class UsingPersonRecord {
System.out.println(p.firstName());
}
}
-=======8<=========
+// =======8<=========
-=======8<=========
+// =======8<=========
public aspect TraceRecordComponents {
before(): execution(public * *()) {
System.out.println(thisJoinPointStaticPart);
}
}
-=======8<=========
+// =======8<=========
....
Compile it with:
+[source, text]
....
$ ajc --enable-preview -14 Person.java UsingPersonRecord.java TraceRecordComponents.java
....
Now run it:
+[source, text]
....
$ java --enable-preview UsingPersonRecord
execution(String Person.toString())
diff --git a/docs/dist/doc/changes.adoc b/docs/dist/doc/changes.adoc
index c7b2d6975..25ef37f09 100644
--- a/docs/dist/doc/changes.adoc
+++ b/docs/dist/doc/changes.adoc
@@ -178,10 +178,10 @@ compiler supports an additional option, -showWeaveInfo, which will
produce informational messages concerning the activity of the weaver.
For example:
+
+[source, text]
....
- Type 'tjp.Demo' (Demo.java:30) advised by around advice from 'tjp.GetInfo'
- (GetInfo.java:26) [RuntimeTest=true]
-
+Type 'tjp.Demo' (Demo.java:30) advised by around advice from 'tjp.GetInfo'
+(GetInfo.java:26) [RuntimeTest=true]
....
* https://bugs.eclipse.org/bugs/show_bug.cgi?id=44191[44191] AspectJ
1.2.1 improves the error messages issued in many of the infamous "can't
diff --git a/docs/dist/doc/porting.adoc b/docs/dist/doc/porting.adoc
index bc95dc5c7..cbf8ede6d 100644
--- a/docs/dist/doc/porting.adoc
+++ b/docs/dist/doc/porting.adoc
@@ -37,35 +37,36 @@ The following example program illustrates the differences in join point
matching with the `call` pointcut designator between 1.4 and 1.3
compliance levels.
-....
-01 class A {
-02 public void doIt() {...};
-03 }
-04
-05 class B extends A {
-06 public void doThisToo() {...};
-07 }
-08
-09
-10 public class CallsAandB {
-11
-12 public static void main(String[] args) {
-13 B b = new B();
-14 A bInDisguise = new B();
-15
-16 b.doIt(); // AspectJ 1.2 matches here
-17 bInDisguise.doIt(); // this is never matched
-18 }
-19
-20 }
-21
-22 aspect CallPCDMatchingExample {
-23
-24 before() : call(* B.doIt(..)) {
-25 System.out.println("About to call B.doIt(...)");
-26 }
-27
-28 }
+[source, java]
+....
+/*01*/ class A {
+/*02*/ public void doIt() {...};
+/*03*/ }
+/*04*/
+/*05*/ class B extends A {
+/*06*/ public void doThisToo() {...};
+/*07*/ }
+/*08*/
+/*09*/
+/*10*/ public class CallsAandB {
+/*11*/
+/*12*/ public static void main(String[] args) {
+/*13*/ B b = new B();
+/*14*/ A bInDisguise = new B();
+/*15*/
+/*16*/ b.doIt(); // AspectJ 1.2 matches here
+/*17*/ bInDisguise.doIt(); // this is never matched
+/*18*/ }
+/*19*/
+/*20*/ }
+/*21*/
+/*22*/ aspect CallPCDMatchingExample {
+/*23*/
+/*24*/ before() : call(* B.doIt(..)) {
+/*25*/ System.out.println("About to call B.doIt(...)");
+/*26*/ }
+/*27*/
+/*28*/ }
....
When this program is compiled with AspectJ 1.2 using the default
@@ -99,8 +100,8 @@ does not match at a join point, and a user may have expected it to.
Compiling the above program using AspectJ 1.2 produces the following
compiler output:
+[source, text]
....
-
CallsAandB.java:24 warning does not match because declaring type is A, if match desired use target(B) [Xlint:unmatchedSuperTypeInCall]
before() : call(* B.doIt(..)) {
^^^^^^^^^^^^^^^
@@ -109,7 +110,6 @@ before() : call(* B.doIt(..)) {
1 warning
-
....
The warning is telling us that the call pointcut associated with the
@@ -147,6 +147,7 @@ an interface is now (correctly) prohibited, and there will no longer be
a constructor-execution join point for the interface. To initialize a
field declared on an interface, use initialization, e.g.,
+[source, java]
....
int I.i;
after(I i) returning: initialization(I) && this(i) { i.i = 2; }
@@ -154,6 +155,7 @@ after(I i) returning: initialization(I) && this(i) { i.i = 2; }
To pick out the constructor-execution for any implementation of I, try
+[source, java]
....
execution(I+.new(..))
....
@@ -172,6 +174,7 @@ older version of BCEL available earlier on your classpath than the
version included in the 1.2 aspectjtools.jar then you will see errors
like:
+[source, text]
....
C:\work\test\TestAspect.aj error Internal compiler error
java.lang.NoSuchMethodError: org.apache.bcel.generic.InstructionFactory.
@@ -219,6 +222,7 @@ Conflicts will be reported for no-argument constructors generated by
compilers when no constructor is defined for a class. That means the
following code will compile in 1.0 but not in 1.1:
+[source, java]
....
class C {}
aspect A {
@@ -243,6 +247,7 @@ The compiler will report an error that the form
`aspect {name} dominates {list}...` is no longer supported. It has been
replaced by a new declare statement:
+[source, java]
....
declare precedence : {name} {list}...
....
@@ -269,6 +274,7 @@ returning advice.
The main change that was made was of after returning advice for
constructor execution join points. Previously, this advice was legal:
+[source, java]
....
after() returning (Foo f): execution(Foo.new(..)) { ... }
....
@@ -280,6 +286,7 @@ constructor calls) do not return the value of the new object. Rather,
void method. With that in mind, any code like the above should be
conveted to the form.
+[source, java]
....
after(Foo f) returning: this(f) && execution(Foo.new(..)) { ... }
....
@@ -287,6 +294,7 @@ after(Foo f) returning: this(f) && execution(Foo.new(..)) { ... }
In compilers prior to 1.0.4, the following advice could pick out join
points
+[source, java]
....
after() returning (String s): call(void foo()) { ... }
....
@@ -294,6 +302,7 @@ after() returning (String s): call(void foo()) { ... }
This is no longer picked out. This pattern was most commonly used in
highly polymorphic contexts, such as
+[source, java]
....
after() returning (String s): call(* foo()) { ... }
....
@@ -301,6 +310,7 @@ after() returning (String s): call(* foo()) { ... }
If you want to capture all calls, binding null objects for those that
would otherwise have no value, you must use the `Object` type.
+[source, java]
....
after() returning (Object o): call(* foo()) { ... }
....
@@ -378,18 +388,20 @@ for example, you named a parameter of a pointcut "set", you should (for
your own sanity -- the compiler doesn't require it) rename it in the
rewritten pointcut.
+[source, java]
....
pointcut sort(Collection set): calls(void addAll(set));
-==>
+// ==>
pointcut sort(Collection mySet): call(void addAll(mySet));
....
While converting to use singular nouns for the primitive pointcuts, you
may also want to remove the "s" from your user-defined pointcuts.
+[source, java]
....
pointcut publicCalls(): calls(public * *(..));
-==>
+// ==>
pointcut publicCall(): call(public * *(..));
....
@@ -412,9 +424,10 @@ straightforward, depending on whether the pointcut exposed state or not.
Receptions pointcuts that did not expose state can simply be replaced by
the new `call` and `target` pointcuts:
+[source, java]
....
receptions(void Foo.m())
-==>
+// ==>
target(Foo) && call(void m())
....
@@ -424,9 +437,10 @@ Some receptions pointcuts exposed the receiving object by replacing the
receiving type with a pointcut formal. These PCDs should be rewritten to
use the new `target` pointcut to expose the receiving object.
+[source, java]
....
pointcut fooCallees(Foo f): receptions(void f.m());
-==>
+// ==>
pointcut fooCallee(Foo f): target(f) && call(void m());
....
@@ -434,9 +448,10 @@ Like xref:#_1_0a1-fixing-state-access[other pointcuts], receptions
pointcuts that exposed one or more arguments should be rewritten to use
the `args` pointcut:
+[source, java]
....
pointcut intPassers(int i, int j): receptions(void Foo.m(i, j));
-==>
+// ==>
pointcut intPasser(int i, int j):
args(i, j) && target(Foo) && call(void m(int, int));
....
@@ -453,9 +468,10 @@ but also of classes that extended C.
If you want this behaviour, then you need to use the new subtypes
operator, +, on the type name in question. So,
+[source, java]
....
receptions(C.new())
-==>
+// ==>
call(C+.new())
....
@@ -468,6 +484,7 @@ allow all kinds of advice it may be that the object isn't constructed
yet (say, in before or around advice). This is a benefit, in that it
allows caching constructed objects
+[source, java]
....
aspect Singleton {
private C theC = null;
@@ -482,9 +499,10 @@ aspect Singleton {
but it does require some rewriting. The new object can be accessed as
the return value in after returning advice. So,
+[source, java]
....
after(Point p) returning (): receptions(p.new(int, int)) { ... }
-==>
+// ==>
after() returning (Point p): call(Point+.new(int, int)) { ... }
....
@@ -509,15 +527,17 @@ Any time you have a pointcut that has a signature where one of the
arguments was a pointcut or advice formal, just replace that formal with
its type and add an `args` pointcut.
+[source, java]
....
pointcut intPassers(int i, int j): calls(void Foo.m(i, j));
-==>
+// ==>
pointcut intPasser(int i, int j): args(i, j) && call(void Foo.m(int, int));
....
+[source, java]
....
pointcut stringPassers(String s): receptions(void Foo.m(s, ..));
-==>
+// ==>
pointcut stringPasser(String s): args(s, ..) && call(void Foo.m(String, ..));
....
@@ -525,6 +545,7 @@ pointcut stringPasser(String s): args(s, ..) && call(void Foo.m(String, ..));
If a calls pointcut exposed the the receiving object, such as
+[source, java]
....
pointcut fooCallees(Foo f): calls(void f.m());
....
@@ -532,6 +553,7 @@ pointcut fooCallees(Foo f): calls(void f.m());
then the new version should use the `target` pointcut to get at that
object
+[source, java]
....
pointcut fooCallee(Foo f): target(f) && call(void Foo.m());
....
@@ -543,9 +565,10 @@ returning advice, when it is guaranteed that the object was successfully
constructed. So instead of using the `target` pointcut to expose the
value, you should use the normal `after returning` mechanism:
+[source, java]
....
after(Point p) returning (): calls(p.new(int, int)) { ... }
-==>
+// ==>
after() returning (Point p): call(Point+.new(int, int)) { ... }
....
@@ -555,15 +578,17 @@ Exposing the target object of a `gets` or `sets` pointcut should be done
the same way it was for `calls` pointcuts, with the new `target`
pointcut.
+[source, java]
....
before(Frame f): gets(Color f.color) { ... }
-==>
+// ==>
before(Frame f): target(f) && get(Color Frame.color) { ... }
....
+[source, java]
....
before(Frame f): sets(Color f.color) { ... }
-==>
+// ==>
before(Frame f): target(f) && set(Color Frame.color) { ... }
....
@@ -573,11 +598,14 @@ the field yourself in the body. Depending on the rest of your system,
you may need to restrict the advice from the aspect body to eliminiate
the circularity.
+[source, java]
....
aspect A {
before(Frame f, Color c): gets(Color f.color)[c] { ... }
}
-==>
+
+// ==>
+
aspect A {
before(Frame f):
target(f) && get(Color Frame.color) && !within(A) {
@@ -590,11 +618,14 @@ aspect A {
The same can be done for `around` advice. However, the only way to port
after advice that needs the old value is to convert it to around advice.
+[source, java]
....
aspect A {
after(Frame f, Color c) returning (): gets(Color f.color)[c] { ... }
}
-==>
+
+// ==>
+
aspect A {
void around(Frame f):
target(f) && get(Color Frame.color) && !within(A) {
@@ -610,9 +641,10 @@ available, but not the way it was previously. Instead of using the
square bracket syntax, we use an `args` pointcut. All set join points
are assumed to have exactly one argument, which holds the new value. So,
+[source, java]
....
after(Color newColor): sets(Color Frame.color)[][newColor] { ... }
-==>
+// ==>
after(Color newColor): args(newColor) && set(Color Frame.color) { ... }
....
@@ -625,9 +657,10 @@ The value of the exception at an exception handler join point is now
accessed through the `args` pointcut; all exception handler join points
are treated as having exactly one argument, the exception value. So,
+[source, java]
....
before(NotFoundException e): handlers(e) { ... }
-==>
+// ==>
before(NotFoundException e): args(e) && handler(NotFoundException) { ... }
....
@@ -640,9 +673,10 @@ closed, and within can only take type patterns, not pointcut or advice
formals. A use of the `this` pointcut will capture what previous
implementations did:
+[source, java]
....
pointcut usesFoo(Foo f): within(f);
-==>
+// ==>
pointcut usesFoo(Foo f): this(f) && within(Foo);
....
@@ -667,6 +701,7 @@ to match.
For example, the pointcut
+[source, java]
....
calls(void m(Object))
....
@@ -677,6 +712,7 @@ out method calls to methods that are defined to take exactly the type
Object, which may be a lot fewer join points. If you want the old
behaviour, simply convert to
+[source, java]
....
call(void m(Object+))
....
@@ -692,10 +728,11 @@ pointcut, composed (with `&&`) with another pointcut. If the other
pointcut was a `receptions` pointcut, then `instanceof` should be
converted to `target` (and `receptions` converted to `call`). So,
+[source, java]
....
pointcut stateChanges(Subject s):
instanceof(s) && receptions(void Button.click());
-==>
+// ==>
pointcut stateChange(Subject s):
target(s) && call(void Button.click());
....
@@ -703,15 +740,17 @@ pointcut stateChange(Subject s):
In all other cases, `instanceof` referred to the currently executing
object, and so should be converted into `this`
+[source, java]
....
before(Point p): instanceof(p) && executions(* makePolar(..)) { ... }
-==>
+// ==>
before(Point p): this(p) && execution(* makePolar(..)) { ... }
....
+[source, java]
....
pointcut setup(Client c): instanceof(c) && calls(Remote Naming.lookup(String));
-==>
+// ==>
pointcut setup(Client c): this(c) && calls(Remote Naming.lookup(String));
....
@@ -728,9 +767,10 @@ fields.
The old behaviour can be recovered with a simple rewrite.
+[source, java]
....
initializations(A)
-==>
+// ==>
initialization(A.new(..)) && !execution(A.new(..))
....
@@ -760,20 +800,22 @@ If the aspect whose presense you are checking for was defined
`of eachcflow`, `of eachcflowbelow`, or, more unlikely, `of eachJVM()`,
then the conversion is simple:
+[source, java]
....
hasaspect(A)
-==>
+// ==>
if(A.hasAspect())
....
If the aspect was defined `of eachobject`, then you will have to expose
the current object in your pointcut or advice parameters:
+[source, java]
....
pointcut cut(): hasaspect(A) ... ;
-==>
+// ==>
pointcut cut(Object o): this(o) && if(A.hasAspect(o)) ... ;
-or
+// or
pointcut cut(Object o): target(o) && if(A.hasAspect(o)) ... ;
....
@@ -782,11 +824,12 @@ aspect, then you can get the same state by using `A.aspectOf()` in the
body of the advice. For example, if the aspect A were defined
`of eachcflow`, then
+[source, java]
....
before(A myA): hasaspect(myA) {
myA.checkStatus();
}
-==>
+// ==>
before(): if(A.hasAspect()) {
A myA = A.aspectOf();
myA.checkStatus();
@@ -801,9 +844,10 @@ of within and the xref:#_1_0a1-subtypes-to-plus[new subtypes operator],
+, instead. You'll save two characters and be using a simpler and more
orthogonal language.
+[source, java]
....
withinall(Foo)
-==>
+// ==>
within(Foo+)
....
@@ -813,9 +857,10 @@ within(Foo+)
The returns keyword is no longer necessary for user-defined pointcuts.
Simply remove it when you find it.
+[source, java]
....
pointcut publicIntCalls() returns int: calls(public int *(..));
-==>
+// ==>
pointcut publicIntCall(): call(public int *(..));
....
@@ -864,9 +909,10 @@ programs easier. There is one ugly idiom, however, that this change
disposes of. If your program includes the type pattern `*..*`, which
used to match all types, you can replace it with the much simpler *.
+[source, java]
....
pointcut unaryVoidMethods(): call(void *(*..*));
-==>
+// ==>
pointcut unaryVoidMethod(): call(void *(*));
....
@@ -882,11 +928,12 @@ wrote `subtypes(Foo)`, i.e., the subtypes of a single type, simply
replace this with `Foo+`. Otherwise, use the + operator as appropriate
in `TypePattern`.
+[source, java]
....
public void (subtypes(Target0 || Target1)).accept(Visitor v) {
v.visit(this);
}
-==>
+// ==>
public void (Target0+ || Target1+).accept(Visitor v) {
v.visit(this);
}
@@ -901,9 +948,10 @@ public void (Target0+ || Target1+).accept(Visitor v) {
The returns keyword is no longer used for around advice. Instead, the
return type is declared as it is for methods. So,
+[source, java]
....
around(Point p) returns void: setters(p) { ... }
-==>
+// ==>
void around(Point p): setter(p) { ... }
....
@@ -913,6 +961,7 @@ void around(Point p): setter(p) { ... }
Around advice must now declare the checked exceptions it throws with a
`throws` clause, much like a method.
+[source, java]
....
char around(char c) throws java.io.CharConversionException: converter(c) {
char result;
@@ -951,6 +1000,7 @@ This allows interesting advice interaction. In the following advice, for
example, the `after throwing` advice will catch the exception thrown by
the `before` advice
+[source, java]
....
aspect A {
before(): call(void main(..)) {
@@ -965,6 +1015,7 @@ aspect A {
But reversing the order will give the `before` advice more precedence,
making its exception uncatchable by the `after throwing` advice
+[source, java]
....
aspect A {
after() throwing(RuntimeException e): call(void main(..)) {
@@ -986,15 +1037,17 @@ If you use after returning advice and do not need to expose the return
value, you no longer need to write an empty set of parentheses to
indicate that fact. So,
+[source, java]
....
after(Formals) returning (): Pointcut { ... }
-==>
+// ==>
after(Formals) returning: Pointcut { ... }
....
The same syntax is now available for after throwing advice, in case you
do not care what `Throwable` is thrown.
+[source, java]
....
after(Formals) throwing: Pointcut { ... }
....
@@ -1013,6 +1066,7 @@ The `JoinPoint` object hierarchy has been folded into a single class,
`org.aspectj.lang.JoinPoint`. A common pattern in logging, for example,
was
+[source, java]
....
before() executions(* myMethod()) {
ExecutionJoinPoint jp = (ExecutionJoinPoint)thisJoinPoint;
@@ -1025,6 +1079,7 @@ before() executions(* myMethod()) {
While there is still a rich hierarchy for signatures, there is only one
`JoinPoint` type, so this can be rewritten as:
+[source, java]
....
before() executions(* myMethod()) {
JoinPoint jp = thisJoinPoint;
@@ -1045,12 +1100,14 @@ Some of the method names of `JoinPoint` have been reorganized, as well.
The keywords `+implements` and `+extends` no longer exist. Instead,
AspectJ uses the `declare` form for exactly the same functionality.
+[source, java]
....
Point +implements Serializable;
=>
declare parents: Point implements Serializable;
....
+[source, java]
....
MyButton +extends ButtonAdaptor;
=>
@@ -1063,6 +1120,7 @@ declare parents: MyButton extends ButtonAdaptor;
Around advice advice no longer effects the static exception checking of
Java. This means that the following code previously compiled:
+[source, java]
....
class C {
void noExceptionDeclared() {
@@ -1088,6 +1146,7 @@ exceptionDeclared() will not, actually, throw an exception, we now
"soften" that exception, that is, take it out of the space of declared
exceptions.
+[source, java]
....
declare soft: ExceptionType: Pointcut;
....
@@ -1097,6 +1156,7 @@ would require runtime information. But picking out method calls is just
fine. So in order to make the above example work, one new declaration is
needed:
+[source, java]
....
declare soft: IOException:
call(void C.exceptionDeclared()) &&
@@ -1109,9 +1169,10 @@ declare soft: IOException:
The syntax of "of each" modifiers has changed. For `of eachcflow` and
`of eachcflowbelow`, you can simply replace "of each" with "per". So,
+[source, java]
....
aspect A of eachcflow(...) { ... }
-==>
+// ==>
aspect A percflow(...) { ... }
....
@@ -1120,11 +1181,12 @@ remove that declaration entirely (because this is the default
behaviour), or replace the `of eachJVM()` declaration with an
`issingleton` declaration.
+[source, java]
....
aspect of eachJVM() { ... }
-==>
+// ==>
aspect A { ... }
-or
+// or
aspect A issingleton { ... }
....
@@ -1135,13 +1197,16 @@ you replace with depends on the `Pointcut` you use.
If you use a pointcut that picked out reception join points, then use
`pertarget`, and rewrite the pointcut to pick out call join points. So
+[source, java]
....
aspect Shadow
of eachobject(receptions(void Point.setX(int)) ||
receptions(void Point.setY(int))) {
...
}
-==>
+
+// ==>
+
aspect Shadow pertarget(call(void Point.setX(int)) ||
call(void Point.setY(int))) {
...
@@ -1193,7 +1258,7 @@ In many cases, you may not care whether the points of `Pointcut` are
included or not, and so can safely leave `cflow(Pointcut)` pointcut
designators alone. However, if you use the idiom
-[source,codeindent]
+[source, java]
----
Pointcut && ! cflow(Pointcut)
----
@@ -1201,7 +1266,7 @@ Pointcut && ! cflow(Pointcut)
to capture the non-recursive entries to a particular pointcut, you will
definitely want to rewrite that as
-[source,codeindent]
+[source, java]
----
Pointcut && ! cflowbelow(Pointcut)
----
@@ -1212,14 +1277,14 @@ The primitive pointcut designator `cflowtop(Pointcut)` has been removed
from the language, as it is expressible with `cflow` or `cflowbelow`.
All uses of `cflowtop(Pointcut)` can be rewritten as:
-[source,codeindent]
+[source, java]
----
cflowbelow(Pointcut && ! cflowbelow(Pointcut))
----
Though in most cases the following is sufficient
-[source,codeindent]
+[source, java]
----
cflow(Pointcut && ! cflowbelow(Pointcut))
----
@@ -1232,7 +1297,7 @@ override all of its abstract pointcuts with an empty pointcut. AspectJ
0.8beta3 enforces the restriction that a concrete aspect may not have
any abstract pointcuts. Thus the following extension:
-[source,codeindent]
+[source, java]
----
abstract aspect A {
abstract pointcut pc();
@@ -1245,14 +1310,14 @@ will no longer compile.
Adding the new empty pointcut designator
-[source,codeindent]
+[source, java]
----
pointcut Id();
----
in the declaration of the concrete aspect fixes this problem.
-[source,codeindent]
+[source, java]
----
abstract aspect A {
abstract pointcut pc();
@@ -1269,7 +1334,7 @@ aspect B {
Previously, the compiler silently refrained from applying a piece of
advice to join points within its own advice body. So, for example, in
-[source,codeindent]
+[source, java]
----
class C {
static int i;
@@ -1292,7 +1357,7 @@ Most cases of this error can be fixed by correctly specifying the
desired pointcut: In the above example, the intention is clearly not to
trace _all_ references of `C.i`, just those outside the aspect.
-[source,codeindent]
+[source, java]
----
class C {
static int i;
@@ -1310,7 +1375,7 @@ code in the aspect, but not in the particular piece of advice. In such
cases, you can pull the body of the advice into a method and restrict
away from that method (and away from calls to that method):
-[source,codeindent]
+[source, java]
----
class C {
static int i;
@@ -1353,10 +1418,10 @@ to the 0.8beta1 release of AspectJ.
The syntax of introduction has changed. Porting most programs should
require some simple editing. Anywhere you have an introduction block
-[source,codeindent]
+[source, java]
----
introduction GTN {
- ...
+ // ...
}
----
@@ -1368,7 +1433,7 @@ For field introduction, place the `GTN` in front of the field name, and
for constructor introduction, place the `GTN` in front of the `new`
identifier.
-[source,codeindent]
+[source, java]
----
introduction Foo {
public void doStuff() { this.doStuffLater(); }
@@ -1376,7 +1441,7 @@ introduction Foo {
public new(int x) { super(); calorieCount = x; }
}
-==>
+// ==>
public void Foo.doStuff() { this.doStuffLater(); }
public int Foo.calorieCount= 3;
@@ -1387,14 +1452,14 @@ For implements and extends introduction, move the `GTN` in front of the
new identifiers `implements` or `extends`, and place that in a
`declare parents` form.
-[source,codeindent]
+[source, java]
----
introduction Foo {
implements Comparable;
extends Goo;
}
-==>
+// ==>
declare parents: Foo implements Comparable;
declare parents: Foo extends Goo;
@@ -1404,13 +1469,13 @@ In all cases, if the `GTN` is just a type name, it can be moved down on
its own. However, if the `GTN` uses any of `&&`, `||`, and `!`, it must
be parenthesized.
-[source,codeindent]
+[source, java]
----
introduction subtypes(Foo) && !Goo {
int x;
}
-==>
+// ==>
int (Foo+ && !Goo).x;
----
@@ -1423,7 +1488,7 @@ need to modify your code to avoid this accessibility issue, or you will
need to use the `privileged` modifier on the aspect that contains the
introduction.
-[source,codeindent]
+[source, java]
----
class Counter {
private int count = 2;
@@ -1435,7 +1500,8 @@ aspect ExposeCountersPrivates {
}
}
-==>
+// ==>
+
// in 0.8, only privileged aspects can expose a class's privates
privileged aspect ExposeCountersPrivates {
public int Counter.getCount() { return count; }
@@ -1446,7 +1512,7 @@ If you have introduced private or package-protected members, you will
probably have to re-write some code. Most previous uses of introducing
privates can be improved by using private introduction instead.
-[source,codeindent]
+[source, java]
----
class C {
}
@@ -1458,7 +1524,8 @@ aspect AddCounter {
}
}
-==>
+// ==>
+
aspect AddCounter {
private int Counter.count;
public int Counter.getCount() { return count; }
@@ -1491,7 +1558,7 @@ clause or is declared "of eachJVM()", and is not extended by another
aspect, simply remove the keyword "static" from all pieces of advice,
and make sure the aspect is not defined with the "abstract" modifier.
-[source,codeindent]
+[source, java]
----
aspect Tracing {
static before(): executions(* *(..)) {
@@ -1499,7 +1566,7 @@ aspect Tracing {
}
}
-==>
+// ==>
aspect Tracing {
before(): execution(* *(..)) {
@@ -1513,7 +1580,7 @@ advice, is extended, or is "of eachObject(...)" or "of
eachcflowroot(...)", you should group your static advice together and
put it in a new aspect, possibly even an inner aspect.
-[source,codeindent]
+[source, java]
----
aspect ComplexTracing of eachobject(cflow(executions(void Main.main(..)))) {
static before(): executions(* *(..)) {
@@ -1526,7 +1593,7 @@ aspect ComplexTracing of eachobject(cflow(executions(void Main.main(..)))) {
// some other dynamic advice, fields, etc
}
-==>
+// ==>
aspect ComplexTracing of eachobject(cflow(executions(void Main.main(..)))) {
static aspect AlwaysTracing {
@@ -1551,7 +1618,7 @@ majority of your code the most serious change this requires is to add an
explicit `abstract` modifier to a super-aspect that was already
implicitly abstract.
-[source,codeindent]
+[source, java]
----
aspect BaseTracing {
abstract pointcut traced();
@@ -1560,11 +1627,11 @@ aspect BaseTracing {
}
}
-==>
+// ==>
// make this abstract aspect explicitly abstract
abstract aspect BaseTracing {
- ...
+ // ...
}
----
@@ -1576,20 +1643,22 @@ instance of a subaspect back.
This pattern was used in the Spacewar example in the AspectJ
distribution. We had the class hierarchy
+[source, text]
....
- SpaceObject (abstract)
- |- Ship
- |- Bullet
- |- EnergyPellet
+SpaceObject (abstract)
+ |- Ship
+ |- Bullet
+ |- EnergyPellet
....
And the aspect hierarchy
+[source, text]
....
- SpaceObjectDA (abstract)
- |- ShipDA of eachobject(instanceof(Ship))
- |- BulletDA of eachobject(instanceof(Ship))
- |- EnergyPacketDA of eachobject(instanceof(Ship))
+SpaceObjectDA (abstract)
+ |- ShipDA of eachobject(instanceof(Ship))
+ |- BulletDA of eachobject(instanceof(Ship))
+ |- EnergyPacketDA of eachobject(instanceof(Ship))
....
And we would call `SpaceObjectDA.getAspect(SpaceObject)` to access the
@@ -1609,7 +1678,7 @@ defined `of eachobject(instanceof(...))`. A prime example of this was
the `BoundPoint` aspect of the bean example: which needed to associate
each point with a `PropertyChangeSupport` object.
-[source,codeindent]
+[source, java]
----
aspect BoundPoint of eachobject(instanceof(Point)) {
@@ -1630,7 +1699,7 @@ these state association is to use privately introduced fields. Instead
of creating an aspect instance for every `Point` object, store the
`PropertyChagneSupport` object in the `Point` objects themselves.
-[source,codeindent]
+[source, java]
----
aspect BoundPoint {
private PropertyChangeSupport Point.support = new PropertyChangeSupport(this);
diff --git a/docs/faq/faq.adoc b/docs/faq/faq.adoc
index 903406d48..0c6333668 100644
--- a/docs/faq/faq.adoc
+++ b/docs/faq/faq.adoc
@@ -140,9 +140,9 @@ must be able to reach classes in the small (< 100K) runtime library
*A:* From AspectJ's http://eclipse.org/aspectj[web page] , download the
AspectJ distribution. The `jar` file is installed by executing
+[source, text]
....
java -jar jar file name
-
....
Do *not* try to extract the `jar` file contents and then attempt to
@@ -503,6 +503,7 @@ AKA agile methods)?
*A:* From a question on the user list:
+[source, text]
....
> Anyone know the connections between AOP and Extreme Programming?
> I am really confused. It seems AOP is a programming paradigm, which
@@ -510,7 +511,6 @@ AKA agile methods)?
> this is a lightweight software development process. One of the common
> motivations of AOP and XP is designed to adopt to the requirement
> changes, so that it can save the cost of software development.
-
....
This is Raymond Lee's answer:
@@ -649,6 +649,7 @@ in a modular way, something that would otherwise be spread throughout
the code. Consider the following code, adapted from the AspectJ
tutorial:
+[source, java]
....
aspect PublicErrorLogging {
Log log = new Log();
@@ -660,7 +661,6 @@ aspect PublicErrorLogging {
log.write(o, e);
}
}
-
....
The effect of this code is to ensure that whenever any public method of
@@ -838,6 +838,7 @@ below shows how the different profiles build on top of the two
configurations CDC (Connected Device Configuration) and CLDC (Connected
Limited Device Configuration):
+[source, text]
....
--------------
| Personal |
@@ -848,7 +849,6 @@ Limited Device Configuration):
------------------------------------------
| Java |
------------------------------------------
-
....
Which configuration you have dictates the restrictions when running
@@ -1007,18 +1007,18 @@ Environment Guide] link:devguide/ajc-ref.html[Reference for ajc].
line-delimited text file and direct ajc to that file using `-argfile` or
`@`:
+[source, text]
....
ajc @sources.lst
ajc -argfile sources.lst
-
....
Another way in AspectJ 1.1 is to use the `-sourceroots` options, which
reads all source files in a given set of directories:
+[source, text]
....
ajc -sourceroots "src;testsrc"
-
....
For more information, see the link:devguide/index.html[Development
@@ -1063,23 +1063,23 @@ Here's an example of using `ajc` in this sort of cross-compilation mode
(assuming a Windows platform with all the default installation
directories):
+[source, text]
....
ajc -target 1.1 -bootclasspath c:\jdk1.1.7\lib\classes.zip \
-classpath c:\aspectj1.0\lib\aspectjrt.jar -extdirs "" \
-argfile jdk11system.lst
-
....
This same technique can be used if you want to run `ajc` on a JDK 1.3
JVM (highly recommended) but need to generate code for JDK 1.2. That
would look something like:
+[source, text]
....
ajc -bootclasspath c:\jdk1.2\jre\lib\rt.jar \
-classpath c:\aspectj1.0\lib\aspectjrt.jar \
-extdirs c:\jdk1.2\jre\lib\ext
-argfile jdk12system.lst
-
....
*Q:* Does the `ajc` compiler support the `assert` keyword in Java 1.4?
@@ -1226,10 +1226,10 @@ which will be affected by any advice specifying the same pointcut. For
example, the following will print a warning whereever some code in class
Bar gets a field value from Foo:
+[source, java]
....
declare warning: get(* Foo.*) && within(Bar)
: "reading Foo state from Bar";
-
....
When you are running your program, you can trace advice as it executes.
@@ -1282,6 +1282,7 @@ use implement a hybrid build process by listing the production source
files into a javac-compliant argfile, and the development source files
in another ajc argfiles:
+[source, text]
....
-- file "production.lst":
One.java
@@ -1295,21 +1296,20 @@ Trace.java
-- file "development.lst":
@production.lst
@tracing.lst
-
....
Then your development build can use `ajc`:
+[source, text]
....
ajc @development.lst
-
....
And your development build can use `ajc` or `javac` or `jikes`:
+[source, text]
....
jikes @production.lst
-
....
*Q:* We compile module jars and then assemble them. Can we continue this
@@ -1331,6 +1331,7 @@ are visible to other clients, which themselves are otherwise unaffected
by the aspects. In this case, the common library can be built using ajc,
and used on the classpath for the module builds:
+[source, text]
....
ajc -outjar common.jar -sourceroots "aspectj-src:src" ...
cd ../otherProject
@@ -1342,6 +1343,7 @@ should affect two or more modules that are in a dependency relationship
to one another. It should work to reuse the aspects in binary form for
each compile, in dependency order:
+[source, text]
....
ajc -outjar common-aspects.jar
-sourceroots "aspectj-src" ...
@@ -1380,6 +1382,7 @@ libraries).
In Eclipse's AJDT, you can create a top-level project with symbolic
links out to the sources:
+[source, text]
....
app-assembly/
{link common/aspects}
@@ -1425,6 +1428,7 @@ Here's some code Jim Hugunin wrote to trace join points and posted to
the users list. To reuse the aspect, define a subaspect and implement
the pointcuts, for example:
+[source, java]
....
aspect JoinPointSampleAspect extends aj.TraceJoinPoints {
protected pointcut entry() :
@@ -1442,11 +1446,11 @@ aspect JoinPointSampleAspect extends aj.TraceJoinPoints {
class JoinPointSample {
public static void main(String[] args) {}
}
-
....
Here's the aspect:
+[source, java]
....
/* TraceJoinPoints.java */
@@ -1639,6 +1643,7 @@ call? How about the most-recent prior entrypoint?
most-recent recursive call or (b) the current and original recursive
call:
+[source, java]
....
aspect LogFactorial {
pointcut f(int i) : call(int factorial(int)) && args(i);
@@ -1654,7 +1659,6 @@ aspect LogFactorial {
System.err.println(i + "@" + j);
}
}
-
....
*Q:* What is the difference between constructor call, constructor
@@ -1672,6 +1676,7 @@ constructor call obtained using `TraceJointPoints.java` from
#q:seeingjoinpoints[Q:I don't understand what join points exist. How can
I see them?].
+[source, java]
....
public class Init {
public static void main (String[] args) {
@@ -1689,6 +1694,7 @@ class Test extends Super implements I {
For a program compiled with AspectJ 1.0, the result is this:
+[source, xml]
....
<constructor-call sig="Test()" >
<staticinitialization sig="Super._init_" />
@@ -1723,9 +1729,9 @@ of thumb:
* If you want the join point on the "outside" of object creation, use
after returning from call to the constructor:
+
+[source, java]
....
after() returning (Foo newlyCreatedObject): call(Foo.new(..)) { ... }
-
....
+
You might be tempted to use "this" or "target" to expose the new object,
@@ -1734,9 +1740,9 @@ object itself might not be created yet... it only exists "on the way
out", when you return the object.
* If you want the join point inside a particular constructor, use:
+
+[source, java]
....
after(Foo newlyCreatedObject) returning: this(newlyCreatedObject) && execution(Foo.new(..)) { ... }
-
....
+
Remember, though, that if you use "before" advice here, the body of the
@@ -1747,9 +1753,9 @@ object that call each other with `this(...)` and you want exactly one
join point for each initialization of `Foo`, regardless of the path of
constructors it takes, then use:
+
+[source, java]
....
after(Foo f) returning: this(f) && initialization(Foo.new(..)) { ... }
-
....
*Q:* I want advice to run at two join points, but it doesn't run at all.
@@ -1759,9 +1765,9 @@ What gives?
mistake. Most likely you want to do something like "run the advice for
all public and private calls," and the code looks something like this:
+[source, java]
....
within(com.xerox.printing..*) && call(public * *(..)) && call(private * *(..))
-
....
But a pointcut is evaluated at *each* join point. The expression above
@@ -1770,9 +1776,9 @@ has both public and private access. In a pointcut, `pc1() && pc2()`
means both must be true at a given join point for advice to run at that
join point. The correct pointcut would use `||` as follows:
+[source, java]
....
within(com.xerox.printing..*) && (call(public * *(..)) || call(private * *(..)))
-
....
Then the advice will run at the join point.
@@ -1796,6 +1802,7 @@ limited to a certain set of classes. Do I have to retype it each time?
*A:* No. You can declare that all the types implement an interface you
define, and then use the interface type in your program. For example:
+[source, java]
....
/**
* Example of using an interface to represent a type pattern.
@@ -1821,7 +1828,6 @@ abstract aspect MarkerExample {
aspect MyMarker extends MarkerExample {
declare parents: com.mycompany.whatever..* implements Marked;
}
-
....
*Q:* Where do I find example programs and how-to's?
@@ -1886,6 +1892,7 @@ Specification] .
here is the HTML code for an HTML editor applet that contains some
debugging aspects:
+[source, xml]
....
<APPLET
CODE='com.company.swing.applets.EditorApplet'
@@ -1914,6 +1921,7 @@ types to Object, so that highly polymorphic advice may be written. This
works if an advice parameter or the return type for around is typed to
Object. So:
+[source, java]
....
class Test {
static int i;
@@ -1928,15 +1936,14 @@ aspect TraceSet {
System.err.println(val.class);
}
}
-
....
will print out
+[source, text]
....
37
java.lang.Integer
-
....
For more information, see the Programming Guide
@@ -1951,10 +1958,10 @@ flag as an argument.
To programmatically detect the version of the AspectJ runtime while
running under Java 1.4 or later, get the version from the package:
+[source, java]
....
Package lang = org.aspectj.lang.JoinPoint.class.getPackage();
String version = lang.getImplementationVersion();
-
....
When running under Java 1.3 or earlier, read the manifest directly. For
@@ -1973,13 +1980,13 @@ in `org.aspectj.bridge.Version`.
*A:* The only modifier advice can take is `strictfp`. However, you can
enclose the body of the advice in a synchronized clause:
+[source, java]
....
before() : pc() {
synchronized (this) {
// advice code here
}
}
-
....
It should not be necessary to synchronize a percflow aspect, but you
@@ -1999,6 +2006,7 @@ VM exhausts itself in the recursion.
Of course, infinite recursion is possible in Java:
+[source, java]
....
public class Main {
public static void main(String[] args) {
@@ -2009,7 +2017,6 @@ public class Main {
}
}
}
-
....
If you compile and run this program, and it will fail silently, trying
@@ -2018,11 +2025,11 @@ StackOverflowError.
Here's a similar AspectJ program where the recursion is not so obvious:
+[source, java]
....
aspect A {
after(): call(* *(..)) { System.out.println("after " + thisJoinPoint); }
}
-
....
This re-invokes itself because it advises any call. It invokes itself
@@ -2042,19 +2049,20 @@ finally clause, understanding that it may run after some failure.
{empty}(2) Avoid writing advice that advises itself. One simple way to
do so is to exclude the code within the current aspect:
+[source, java]
....
aspect A {
after() returning: !within(A) && call(* *(..)) {
System.out.println("after " + thisJoinPoint);
}
}
-
....
A better way is often to re-write the pointcut. If the advice is
advising itself accidentally, that's a sign that the pointcut is not
saying what you mean.
+[source, java]
....
aspect A {
pointcut withinTargetClasses() : within(A+) || within(B+);
@@ -2062,12 +2070,12 @@ aspect A {
System.out.println("after " + thisJoinPoint);
}
}
-
....
*Q:* I've declared a field on every class in my package; how do I use it
in advice?
+[source, java]
....
aspect A {
boolean com.xerox..*.dirtyFlag;
@@ -2076,7 +2084,6 @@ aspect A {
target.dirtyFlag = true; // compile fails here
}
}
-
....
*A:* You need a type to refer to any member, field or method. It's
@@ -2084,6 +2091,7 @@ generally better to introduce onto an interface and declare classes to
implement the interface, which permits you to use the interface type in
advice formals.
+[source, java]
....
aspect A {
interface TrackingSets {}
@@ -2095,7 +2103,6 @@ aspect A {
target.dirtyFlag = true;
}
}
-
....
*Q:* The AspectJ compiler aborts with an OutOfMemoryError when compiling
@@ -2182,6 +2189,7 @@ How can I fix this?]. For your IDE, do something similar or follow the
provider's instructions. For example, to increase memory in JBuilder,
edit the `jbuilderX/bin/jbuilder.config` file to have an entry like:
+[source, text]
....
vmparam -Xmx384m
....
@@ -2430,6 +2438,7 @@ not control the code for the method execution), test the context for
`invoke(..)`. Here's a pointcut that tests only if the method name is
correct:
+[source, java]
....
aspect A {
pointcut runReflectiveCall(Method run) : target(run) &&
@@ -2438,7 +2447,6 @@ aspect A {
System.out.println("before reflective call " + thisJoinPoint);
}
}
-
....
*Q:* What are the bugs now most affecting users?
@@ -2502,11 +2510,11 @@ CGLIB generate code from the weaving process by appropriate use of the
exclude element in the aop.xml. A typical clause in the aop.xml might
look as follows:
+[source, xml]
....
<weaver>
<exclude within="*CGLIB*" />
</weaver>
-
....
[[aj11]]
@@ -2653,6 +2661,7 @@ only XML. This means aspect developers can write abstract aspects, and
deployers need only configure `aop.xml` and run using the AspectJ weaver
in Java 5. For example, to run Java 5 VM with load-time weaving,
+[source, text]
....
java -javaagent:aspectjweaver.jar -classpath "aspects.jar:${CLASSPATH}" ..
....
@@ -2661,6 +2670,7 @@ To declare a concrete aspect, add a a concrete-aspect XML entity to
`META-INF/aop.xml`. This example extends a tracing aspect to apply to
every type in the application:
+[source, xml]
....
<concrete-aspect
name="com.company.tracing.ConcreteTracing"
@@ -2987,10 +2997,10 @@ AJDT development environment and running the correctness tests. Then:
* Create a file `aspectjlib.properties` within the `org.aspectj.ajde`
project and add the following two lines
+
+[source, text]
....
aspectj.lib.dir=C:/eclipse/aspectj-workspace/aj-build/dist/tools/lib
aspectj.doc.dir=C:/eclipse/aspectj-workspace/aj-build/dist/ide/eclipse/org.aspectj.ajde.doc/doc
-
....
+
making sure to change the path to correspond to your set up.
@@ -3043,6 +3053,7 @@ is a sample file with some example definitions, preceded by comments
showing the directory layout of the files referred to in the test
definitions.
+[source, xml]
....
<!DOCTYPE suite SYSTEM "../tests/ajcTestSuite.dtd">
<suite>
@@ -3137,10 +3148,10 @@ tree as described in #q:buildingsource[Q:How do I get and compile the
source code for AspectJ?] and then build the `build-testing-drivers`
target:
+[source, text]
....
cd build
../lib/ant/bin/ant -f build.xml build-testing-drivers
-
....
This produces `../aj-build/jars/testing-drivers-all.jar` which you can
@@ -3237,8 +3248,7 @@ http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AJDT ).
Bug reports on ajbrowser should have version information for both Java
and AspectJ, and (most importantly) clear steps for reproducing the bug.
You may submit ajbrowser bugs against the IDE component of AspectJ via
-the web form http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ
-.
+the web form http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ.
One of the benefits of open-source is that you can find and fix the bug
for yourself; when you submit the fix back to us, we can validate the
@@ -3422,7 +3432,7 @@ More details for 1.0 and earlier releases are available in changes.html.
*Q:* What is the AspectJ development schedule?
*A:* Below is a table describing the goals for the major releases. For
-information about specific features, search the bug database for `RFE`'s
+information about specific features, search the bug database for ``RFE``'s
("requests for enhancement") by
http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&bug_severity=enhancement[selecting
severity of "enhancement"]. Like many open-source projects, we don't
diff --git a/docs/pdGuideDB/ajcore.adoc b/docs/pdGuideDB/ajcore.adoc
index a130309f9..5928d372d 100644
--- a/docs/pdGuideDB/ajcore.adoc
+++ b/docs/pdGuideDB/ajcore.adoc
@@ -44,6 +44,7 @@ dump configuration as well as the exception (with stack trace) that is
the source of the problem and any messages issued by the compiler. Most
importantly the exact version of AspectJ is included.
+[source, text]
....
---- AspectJ Properties ---
AspectJ Compiler DEVELOPMENT built on Tuesday Jul 25, 2006 at 13:00:09 GMT
@@ -157,5 +158,4 @@ java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory
at org.aspectj.tools.ajc.Main.run(Main.java:367)
at org.aspectj.tools.ajc.Main.runMain(Main.java:246)
at org.aspectj.tools.ajc.Main.main(Main.java:86)
-
....
diff --git a/docs/pdGuideDB/ltwdump.adoc b/docs/pdGuideDB/ltwdump.adoc
index 3f97fb2c1..627be6635 100644
--- a/docs/pdGuideDB/ltwdump.adoc
+++ b/docs/pdGuideDB/ltwdump.adoc
@@ -31,6 +31,7 @@ package (and subpackages) but not CGLIB generated classes in the
`com.foo.bar` package (and subpackages). It will also ensure all woven
byte-code is dumped both before and after weaving.
+[source, xml]
....
<aspectj>
<aspects>
@@ -46,6 +47,7 @@ byte-code is dumped both before and after weaving.
You should see messages similar to this:
+[source, text]
....
[WeavingURLClassLoader] info AspectJ Weaver Version 1.5.3 built on Thursday Oct 26, 2006 at 17:22:31 GMT
[WeavingURLClassLoader] info register classloader org.aspectj.weaver.loadtime.WeavingURLClassLoader
@@ -57,6 +59,7 @@ You should see messages similar to this:
On disk you would find the following files:
+[source, text]
....
_ajdump/_before/com/foo/bar/Test.class
_ajdump/com/foo/bar/Test.class
diff --git a/docs/pdGuideDB/messages.adoc b/docs/pdGuideDB/messages.adoc
index ba0ca116a..277a4f472 100644
--- a/docs/pdGuideDB/messages.adoc
+++ b/docs/pdGuideDB/messages.adoc
@@ -103,6 +103,7 @@ during LTW. The following example will produce basic informational
messages about the lifecyle of the weaver in addition to any warning or
error messages.
+[source, xml]
....
<aspectj>
<weaver options="-verbose">
@@ -116,6 +117,7 @@ defining class loader associated with weaver. You can use this
information in a large system to distinguish between different
applications each of which will typically have its own class loader.
+[source, text]
....
[AppClassLoader@92e78c] info AspectJ Weaver Version 1.5.3 built on Thursday Oct 26, 2006 at 17:22:31 GMT
[AppClassLoader@92e78c] info register classloader sun.misc.Launcher$AppClassLoader@92e78c
@@ -133,6 +135,7 @@ weaving (LTW), why advice has not been woven. Here is a quick guide to
the messages to look for. Firstly if you use the `-verbose` option you
should see the following message when your aspect is registered:
+[source, text]
....
info register aspect MyAspect
....
@@ -140,6 +143,7 @@ info register aspect MyAspect
Secondly if you use the `-debug` option you should see a message
indicating that you class is being woven:
+[source, text]
....
debug weaving 'HelloWorld'
....
@@ -150,6 +154,7 @@ determine whether your pointcuts match you can use the `-showWeaveInfo`
option which will cause a message to be issued each time a join point is
woven:
+[source, text]
....
weaveinfo Join point 'method-execution(void HelloWorld.main(java.lang.String[]))' ...
....
diff --git a/docs/pdGuideDB/trace.adoc b/docs/pdGuideDB/trace.adoc
index bfe20557e..a752e0262 100644
--- a/docs/pdGuideDB/trace.adoc
+++ b/docs/pdGuideDB/trace.adoc
@@ -82,6 +82,7 @@ Below is an extract from that trace with method arguments removed. You
will notice the millisecond time stamp, thread id and indication of
entry/exit/event or message type for each line of trace.
+[source, text]
....
15:44:18.630 main > org.aspectj.weaver.loadtime.Aj.<init>
15:44:18.660 main < org.aspectj.weaver.loadtime.Aj.<init>
@@ -133,6 +134,7 @@ below could be used to configure Java Logging. The resulting file, just
containing trace for the `org.aspectj.weaver.loadtime` package, will be
written to `java0.log` in your `user.home` directory.
+[source, text]
....
handlers= java.util.logging.FileHandler
@@ -150,6 +152,7 @@ By setting the System property `-Dorg.aspectj.tracing.debug=true` you
should see a message confirming which trace infrastructure is being
used.
+[source, text]
....
TraceFactory.instance=org.aspectj.weaver.tools.Jdk14TraceFactory@12dacd1
....
diff --git a/docs/progGuideDB/examples.adoc b/docs/progGuideDB/examples.adoc
index fccd57eff..5b20a1b4e 100644
--- a/docs/progGuideDB/examples.adoc
+++ b/docs/progGuideDB/examples.adoc
@@ -7,35 +7,27 @@ This chapter consists entirely of examples of AspectJ use.
The examples can be grouped into four categories:
-technique
-
-Examples which illustrate how to use one or more features of the
-language.
-
-development
-
-Examples of using AspectJ during the development phase of a project.
-
-production
-
-Examples of using AspectJ to provide functionality in an application.
-
-reusable
-
-Examples of reuse of aspects and pointcuts.
+technique::
+ Examples which illustrate how to use one or more features of the language
+development::
+ Examples of using AspectJ during the development phase of a project
+production::
+ Examples of using AspectJ to provide functionality in an application
+reusable::
+ Examples of reuse of aspects and pointcuts
[[examples-howto]]
=== Obtaining, Compiling and Running the Examples
The examples source code is part of the AspectJ distribution which may
-be downloaded from the AspectJ project page (
-http://eclipse.org/aspectj[] ).
+be downloaded from the https://eclipse.org/aspectj[AspectJ project page].
Compiling most examples is straightforward. Go the `InstallDir/examples`
directory, and look for a `.lst` file in one of the example
subdirectories. Use the `-arglist` option to `ajc` to compile the
example. For instance, to compile the telecom example with billing, type
+[source, text]
....
ajc -argfile telecom/billing.lst
....
@@ -45,11 +37,13 @@ Java archive (`aspectjrt.jar`). You may either set the `CLASSPATH`
environment variable or use the `-classpath` command line option to the
Java interpreter:
+[source, text]
....
(In Unix use a : in the CLASSPATH)
java -classpath ".:InstallDir/lib/aspectjrt.jar" telecom.billingSimulation
....
+[source, text]
....
(In Windows use a ; in the CLASSPATH)
java -classpath ".;InstallDir/lib/aspectjrt.jar" telecom.billingSimulation
@@ -64,7 +58,7 @@ dynamic join points and advice, and with static introduction. Advice
changes an application's behavior. Introduction changes both an
application's behavior and its structure.
-The first example, xref:#examples-joinPoints[Join Points and ], is about
+The first example, xref:#examples-joinPoints[Join Points and `thisJoinPoint`], is about
gathering and using information about the join point that has triggered
some advice. The second example, xref:#examples-roles[Roles and Views],
concerns a crosscutting view of an existing class hierarchy.
@@ -87,6 +81,7 @@ join point. Here, for example, since the only join points picked out by
the pointcut are calls of a certain method, we can get the target value
and one of the argument values of the method calls directly.
+[source, java]
....
before(Point p, int x): target(p)
&& args(x)
@@ -101,6 +96,7 @@ But sometimes the shape of the join point is not so clear. For instance,
suppose a complex application is being debugged, and we want to trace
when any method of some class is executed. The pointcut
+[source, java]
....
pointcut execsInProblemClass(): within(ProblemClass)
&& execution(* *(..));
@@ -124,19 +120,16 @@ point
* the currently executing object
* the target object
* an object encapsulating the static information about the join point.
-This is also available through the special variable
-+
-thisJoinPointStaticPart
-+
-.
+This is also available through the special variable `thisJoinPointStaticPart`.
===== The `Demo` class
The class `tjp.Demo` in `tjp/Demo.java` defines two methods `foo` and
`bar` with different parameter lists and return types. Both are called,
-with suitable arguments, by `Demo`'s `go` method which was invoked from
+with suitable arguments, by ``Demo``'s `go` method which was invoked from
within its `main` method.
+[source, java]
....
public class Demo {
static Demo d;
@@ -168,6 +161,7 @@ This aspect uses around advice to intercept the execution of methods
`foo` and `bar` in `Demo`, and prints out information garnered from
`thisJoinPoint` to the console.
+[source, java]
....
aspect GetInfo {
@@ -207,6 +201,7 @@ aspect GetInfo {
The pointcut `goCut` is defined as
+[source, java]
....
cflow(this(Demo)) && execution(void go())
....
@@ -221,7 +216,7 @@ advised.
The name of the method and that method's defining class are available as
parts of the
-xref:../api/org/aspectj/lang/Signature.html[org.aspectj.lang.Signature]
+xref:../api/org/aspectj/lang/Signature.html[`org.aspectj.lang.Signature`]
object returned by calling `getSignature()` on either `thisJoinPoint` or
`thisJoinPointStaticPart`.
@@ -274,7 +269,7 @@ are provided by AspectJ without having to modify the code for the class
The `Point` class defines geometric points whose interface includes
polar and rectangular coordinates, plus some simple operations to
-relocate points. `Point`'s implementation has attributes for both its
+relocate points. ``Point``'s implementation has attributes for both its
polar and rectangular coordinates, plus flags to indicate which
currently reflect the position of the point. Some operations cause the
polar coordinates to be updated from the rectangular, and some have the
@@ -292,20 +287,21 @@ image:aspects.gif[image]
===== The `CloneablePoint` aspect
-This first aspect is responsible for `Point`'s implementation of the
+This first aspect is responsible for ``Point``'s implementation of the
`Cloneable` interface. It declares that `Point implements Cloneable`
with a `declare parents` form, and also publically declares a
-specialized `Point`'s `clone()` method. In Java, all objects inherit the
+specialized ``Point``'s `clone()` method. In Java, all objects inherit the
method `clone` from the class `Object`, but an object is not cloneable
unless its class also implements the interface `Cloneable`. In addition,
classes frequently have requirements over and above the simple
bit-for-bit copying that `Object.clone` does. In our case, we want to
-update a `Point`'s coordinate systems before we actually clone the
+update a ``Point``'s coordinate systems before we actually clone the
`Point`. So our aspect makes sure that `Point` overrides `Object.clone`
with a new method that does what we want.
We also define a test `main` method in the aspect for convenience.
+[source, java]
....
public aspect CloneablePoint {
@@ -338,7 +334,7 @@ public aspect CloneablePoint {
===== The `ComparablePoint` aspect
-`ComparablePoint` is responsible for `Point`'s implementation of the
+`ComparablePoint` is responsible for ``Point``'s implementation of the
`Comparable` interface.
The interface `Comparable` defines the single method `compareTo` which
@@ -349,11 +345,11 @@ class that implement it.
parents` to declare that `Point implements
Comparable`, and also publically declares the appropriate
`compareTo(Object)` method: A `Point` `p1` is said to be less than
-another `Point``
- p2` if `p1` is closer to the origin.
+another `Point p2` if `p1` is closer to the origin.
We also define a test `main` method in the aspect for convenience.
+[source, java]
....
public aspect ComparablePoint {
@@ -391,8 +387,8 @@ public aspect ComparablePoint {
===== The `HashablePoint` aspect
-Our third aspect is responsible for `Point`'s overriding of `Object`'s
-`equals` and `hashCode` methods in order to make `Point`s hashable.
+Our third aspect is responsible for ``Point``'s overriding of ``Object``'s
+`equals` and `hashCode` methods in order to make ``Point``s hashable.
The method `Object.hashCode` returns an integer, suitable for use as a
hash table key. It is not required that two objects which are not equal
@@ -408,14 +404,15 @@ values, or the same `rho` and `theta` values, not just when they refer
to the same object. We do this by overriding the methods `equals` and
`hashCode` in the class `Point`.
-So `HashablePoint` declares `Point`'s `hashCode` and `equals` methods,
-using `Point`'s rectangular coordinates to generate a hash code and to
+So `HashablePoint` declares ``Point``'s `hashCode` and `equals` methods,
+using ``Point``'s rectangular coordinates to generate a hash code and to
test for equality. The `x` and `y` coordinates are obtained using the
appropriate get methods, which ensure the rectangular coordinates are
up-to-date before returning their values.
And again, we supply a `main` method in the aspect for testing.
+[source, java]
....
public aspect HashablePoint {
@@ -489,6 +486,7 @@ Throughout this example we will use a simple application that contains
only four classes. The application is about shapes. The `TwoDShape`
class is the root of the shape hierarchy:
+[source, java]
....
public abstract class TwoDShape {
protected double x, y;
@@ -512,6 +510,7 @@ public abstract class TwoDShape {
`TwoDShape` has two subclasses, `Circle` and `Square`:
+[source, java]
....
public class Circle extends TwoDShape {
protected double r;
@@ -533,6 +532,7 @@ public class Circle extends TwoDShape {
}
....
+[source, java]
....
public class Square extends TwoDShape {
protected double s; // side
@@ -558,12 +558,14 @@ To run this application, compile the classes. You can do it with or
without ajc, the AspectJ compiler. If you've installed AspectJ, go to
the directory `InstallDir/examples` and type:
+[source, text]
....
ajc -argfile tracing/notrace.lst
....
To run the program, type
+[source, text]
....
java tracing.ExampleMain
....
@@ -571,6 +573,7 @@ java tracing.ExampleMain
(we don't need anything special on the classpath since this is pure Java
code). You should see the following output:
+[source, text]
....
c1.perimeter() = 12.566370614359172
c1.area() = 12.566370614359172
@@ -588,6 +591,7 @@ by writing a `Trace` class that is exactly what we would write if we
didn't have aspects. The implementation is in `version1/Trace.java`. Its
public interface is:
+[source, java]
....
public class Trace {
public static int TRACELEVEL = 0;
@@ -605,8 +609,9 @@ calls, and we would hope we had not forgotten any method. But we can do
that more consistently and reliably with the following aspect (found in
`version1/TraceMyClasses.java`):
+[source, java]
....
-aspect TraceMyClasses {
+public aspect TraceMyClasses {
pointcut myClass(): within(TwoDShape) || within(Circle) || within(Square);
pointcut myConstructor(): myClass() && execution(new(..));
pointcut myMethod(): myClass() && execution(* *(..));
@@ -638,6 +643,7 @@ information, we can get it through `thisJoinPointStaticPart`.
To run this version of tracing, go to the directory
`InstallDir/examples` and type:
+[source, text]
....
ajc -argfile tracing/tracev1.lst
....
@@ -645,6 +651,7 @@ ajc -argfile tracing/tracev1.lst
Running the main method of `tracing.version1.TraceMyClasses` should
produce the output:
+[source, text]
....
--> tracing.TwoDShape(double, double)
<-- tracing.TwoDShape(double, double)
@@ -707,6 +714,7 @@ functionality of `Trace - version1` with the crosscutting support of
`TraceMyClasses - version1`. We end up with a `Trace` aspect (found in
`version2/Trace.java`) with the following public interface
+[source, java]
....
abstract aspect Trace {
@@ -721,6 +729,7 @@ abstract aspect Trace {
In order to use it, we need to define our own subclass that knows about
our application classes, in `version2/TraceMyClasses.java`:
+[source, java]
....
public aspect TraceMyClasses extends Trace {
pointcut myClass(): within(TwoDShape) || within(Circle) || within(Square);
@@ -737,6 +746,7 @@ Notice that we've simply made the pointcut `classes`, that was an
abstract pointcut in the super-aspect, concrete. To run this version of
tracing, go to the directory `examples` and type:
+[source, text]
....
ajc -argfile tracing/tracev2.lst
....
@@ -748,6 +758,7 @@ the same trace information as that from version 1.
The entire implementation of the new `Trace` class is:
+[source, java]
....
abstract aspect Trace {
@@ -869,6 +880,7 @@ bound property protocol.
The `Point` class is a very simple class with trivial getters and
setters, and a simple vector offset method.
+[source, java]
....
class Point {
@@ -908,11 +920,12 @@ class Point {
===== The `BoundPoint` aspect
-The `BoundPoint` aspect is responsible for `Point`'s "beanness". The
+The `BoundPoint` aspect is responsible for ``Point``'s "beanness". The
first thing it does is privately declare that each `Point` has a
`support` field that holds reference to an instance of
`PropertyChangeSupport`.
+[source, java]
....
private PropertyChangeSupport Point.support = new PropertyChangeSupport(this);
....
@@ -923,10 +936,11 @@ passing it `this`, an instance of `Point`. Since the `support` field is
private declared in the aspect, only the code in the aspect can refer to
it.
-The aspect also declares `Point`'s methods for registering and managing
+The aspect also declares ``Point``'s methods for registering and managing
listeners for property change events, which delegate the work to the
property change support object:
+[source, java]
....
public void Point.addPropertyChangeListener(PropertyChangeListener listener){
support.addPropertyChangeListener(listener);
@@ -951,6 +965,7 @@ public void Point.hasListeners(String propertyName) {
The aspect is also responsible for making sure `Point` implements the
`Serializable` interface:
+[source, java]
....
declare parents: Point implements Serializable;
....
@@ -959,13 +974,14 @@ Implementing this interface in Java does not require any methods to be
implemented. Serialization for `Point` objects is provided by the
default serialization method.
-The `setters` pointcut picks out calls to the `Point`'s `set` methods:
+The `setters` pointcut picks out calls to the ``Point``'s `set` methods:
any method whose name begins with "`set`" and takes one parameter. The
around advice on `setters()` stores the values of the `X` and `Y`
properties, calls the original `set` method and then fires the
appropriate property change event according to which set method was
called.
+[source, java]
....
aspect BoundPoint {
private PropertyChangeSupport Point.support = new PropertyChangeSupport(this);
@@ -1025,6 +1041,7 @@ that point: calling its set methods and the offset method. Then it
serializes the point and writes it to a file and then reads it back. The
result of saving and restoring the point is that a new point is created.
+[source, java]
....
class Demo implements PropertyChangeListener {
@@ -1059,6 +1076,7 @@ class Demo implements PropertyChangeListener {
To compile and run this example, go to the examples directory and type:
+[source, text]
....
ajc -argfile bean/files.lst
java bean.Demo
@@ -1093,6 +1111,7 @@ The generic parts of the protocol are the interfaces `Subject` and
view `Observer` objects, and a method for getting data about state
changes:
+[source, java]
....
interface Subject {
void addObserver(Observer obs);
@@ -1105,6 +1124,7 @@ interface Subject {
The `Observer` interface is just as simple, with methods to set and get
`Subject` objects, and a method to call when the subject gets updated.
+[source, java]
....
interface Observer {
void setSubject(Subject s);
@@ -1117,6 +1137,7 @@ The `SubjectObserverProtocol` aspect contains within it all of the
generic parts of the protocol, namely, how to fire the `Observer`
objects' update methods when some state changes in a subject.
+[source, java]
....
abstract aspect SubjectObserverProtocol {
@@ -1157,6 +1178,7 @@ its `Subject`.
`Button` objects extend `java.awt.Button`, and all they do is make sure
the `void click()` method is called whenever a button is clicked.
+[source, java]
....
class Button extends java.awt.Button {
@@ -1187,6 +1209,7 @@ Note that this class knows nothing about being a Subject.
ColorLabel objects are labels that support the void colorCycle() method.
Again, they know nothing about being an observer.
+[source, java]
....
class ColorLabel extends Label {
@@ -1212,6 +1235,7 @@ Finally, the `SubjectObserverProtocolImpl` implements the
subject/observer protocol, with `Button` objects as subjects and
`ColorLabel` objects as observers:
+[source, java]
....
package observer;
@@ -1246,6 +1270,7 @@ all `ColorLabel` objects observing that button will `colorCycle`.
buttons and three observers and links them together as subjects and
observers. So to run the demo, go to the `examples` directory and type:
+[source, text]
....
ajc -argfile observer/files.lst
java observer.Demo
@@ -1303,6 +1328,7 @@ involved in many calls at one time. image:telecom.gif[image]
`Customer` has methods `call`, `pickup`, `hangup` and `merge` for
managing calls.
+[source, java]
....
public class Customer {
@@ -1377,6 +1403,7 @@ connection between customers. It does this with a simple state machine
connections can be observed. Connection is an abstract class with two
concrete subclasses: `Local` and `LongDistance`.
+[source, java]
....
abstract class Connection {
@@ -1422,6 +1449,7 @@ abstract class Connection {
The two kinds of connections supported by our simulation are `Local` and
`LongDistance` connections.
+[source, java]
....
class Local extends Connection {
Local(Customer a, Customer b) {
@@ -1432,6 +1460,7 @@ class Local extends Connection {
}
....
+[source, java]
....
class LongDistance extends Connection {
LongDistance(Customer a, Customer b) {
@@ -1448,6 +1477,7 @@ The source files for the basic system are listed in the file
`basic.lst`. To build and run the basic system, in a shell window, type
these commands:
+[source, text]
....
ajc -argfile telecom/basic.lst
java telecom.BasicSimulation
@@ -1466,6 +1496,7 @@ stopped, and returns their difference when asked for the elapsed time.
The aspect `TimerLog` (below) can be used to cause the start and stop
times to be printed to standard output.
+[source, java]
....
class Timer {
long startTime, stopTime;
@@ -1490,6 +1521,7 @@ class Timer {
The `TimerLog` aspect can be included in a build to get the timer to
announce when it is started and stopped.
+[source, java]
....
public aspect TimerLog {
@@ -1509,6 +1541,7 @@ The `Timing` aspect is declares an inter-type field `totalConnectTime`
for `Customer` to store the accumulated connection time per `Customer`.
It also declares that each `Connection` object has a timer.
+[source, java]
....
public long Customer.totalConnectTime = 0;
private Timer Connection.timer = new Timer();
@@ -1518,6 +1551,7 @@ Two pieces of after advice ensure that the timer is started when a
connection is completed and and stopped when it is dropped. The pointcut
`endTiming` is defined so that it can be used by the `Billing` aspect.
+[source, java]
....
public aspect Timing {
@@ -1556,10 +1590,11 @@ responsible to pay for it. It also declares the inter-type method
charged differently. The call charge must be calculated after the timer
is stopped; the after advice on pointcut `Timing.endTiming` does this,
and `Billing` is declared to be more precedent than `Timing` to make
-sure that this advice runs after `Timing`'s advice on the same join
+sure that this advice runs after ``Timing``'s advice on the same join
point. Finally, it declares inter-type methods and fields for `Customer`
to handle the `totalCharge`.
+[source, java]
....
public aspect Billing {
// precedence required to get advice on endtiming in the right order
@@ -1613,6 +1648,7 @@ the method run of the superclass `AbstractSimulation`. This method is
intended to print out the status of the customer, with respect to the
`Timing` feature.
+[source, java]
....
protected void report(Customer c){
Timing t = Timing.aspectOf();
@@ -1626,6 +1662,7 @@ The files timing.lst and billing.lst contain file lists for the timing
and billing configurations. To build and run the application with only
the timing feature, go to the directory examples and type:
+[source, text]
....
ajc -argfile telecom/timing.lst
java telecom.TimingSimulation
@@ -1634,6 +1671,7 @@ java telecom.TimingSimulation
To build and run the application with the timing and billing features,
go to the directory examples and type:
+[source, text]
....
ajc -argfile telecom/billing.lst
java telecom.BillingSimulation
@@ -1669,6 +1707,7 @@ the object whose methods are being traced. This can be achieved in at
least two ways. One way is keep the interface of the methods
`traceEntry` and `traceExit` as it was before,
+[source, java]
....
public static void traceEntry(String str);
public static void traceExit(String str);
@@ -1678,6 +1717,7 @@ In this case, the caller is responsible for ensuring that the string
representation of the object is part of the string given as argument.
So, calls must look like:
+[source, java]
....
Trace.traceEntry("Square.distance in " + toString());
....
@@ -1685,6 +1725,7 @@ Trace.traceEntry("Square.distance in " + toString());
Another way is to enforce the requirement with a second argument in the
trace operations, e.g.
+[source, java]
....
public static void traceEntry(String str, Object obj);
public static void traceExit(String str, Object obj);
@@ -1694,6 +1735,7 @@ In this case, the caller is still responsible for sending the right
object, but at least there is some guarantees that some object will be
passed. The calls will look like:
+[source, java]
....
Trace.traceEntry("Square.distance", this);
....
@@ -1709,6 +1751,7 @@ only a small effect inside the `Trace` class. Here's a partial view at
the implementation of `Trace`, version 3. The differences with respect
to version 2 are stressed in the comments:
+[source, java]
....
abstract aspect Trace {
@@ -1794,6 +1837,7 @@ In fact, esimply excluding the execution join point may not be enough,
if there are calls to other traced methods within it -- in which case,
the restriction should be
+[source, java]
....
&& !cflow(execution(String toString()))
....
@@ -1811,6 +1855,7 @@ every application class.
Finally, to run this version of tracing, go to the directory `examples`
and type:
+[source, text]
....
ajc -argfile tracing/tracev3.lst
....
@@ -1819,12 +1864,14 @@ The file tracev3.lst lists the application classes as well as this
version of the files `Trace.java` and `TraceMyClasses.java`. To run the
program, type
+[source, text]
....
java tracing.version3.TraceMyClasses
....
The output should be:
+[source, text]
....
--> tracing.TwoDShape(double, double)
<-- tracing.TwoDShape(double, double)
diff --git a/docs/progGuideDB/gettingstarted.adoc b/docs/progGuideDB/gettingstarted.adoc
index 0dbb85056..f22c9cefd 100644
--- a/docs/progGuideDB/gettingstarted.adoc
+++ b/docs/progGuideDB/gettingstarted.adoc
@@ -39,7 +39,7 @@ testing and performance tuning of applications. And, in the section
following, xref:#starting-production[Production Aspects], we present
aspects that implement crosscutting functionality common in Java
applications. We will defer discussing a third category of aspects,
-reusable aspects, until xref:language.adoc[The AspectJ Language].
+reusable aspects, until xref:language.adoc#language[The AspectJ Language].
These categories are informal, and this ordering is not the only way to
adopt AspectJ. Some developers may want to use a production aspect right
@@ -56,7 +56,7 @@ language, but this is by no means a complete overview of AspectJ.
The features are presented using a simple figure editor system. A
`Figure` consists of a number of `FigureElements`, which can be either
-`Point`s or `Line`s. The `Figure` class provides factory services. There
+``Point``s or ``Line``s. The `Figure` class provides factory services. There
is also a `Display`. Most example programs later in this chapter are
based on this system as well.
@@ -143,17 +143,19 @@ context_ of the original call join point.
In AspectJ, _pointcuts_ pick out certain join points in the program
flow. For example, the pointcut
+[source, java]
....
call(void Point.setX(int))
....
picks out each join point that is a call to a method that has the
-signature `void Point.setX(int)` - that is, `Point`'s void `setX` method
+signature `void Point.setX(int)` - that is, ``Point``'s void `setX` method
with a single `int` parameter.
A pointcut can be built out of other pointcuts with and, or, and not
(spelled `&&`, `||`, and `!`). For example:
+[source, java]
....
call(void Point.setX(int)) ||
call(void Point.setY(int))
@@ -165,6 +167,7 @@ picks out each join point that is either a call to `setX` or a call to
Pointcuts can identify join points from many different types - in other
words, they can crosscut types. For example,
+[source, java]
....
call(void FigureElement.setXY(int,int)) ||
call(void Point.setX(int)) ||
@@ -182,6 +185,7 @@ crosscutting concern, it is a bit of a mouthful. So AspectJ allows
programmers to define their own named pointcuts with the `pointcut`
form. So the following declares a new, named pointcut:
+[source, java]
....
pointcut move():
call(void FigureElement.setXY(int,int)) ||
@@ -202,6 +206,7 @@ _property-based_ crosscutting. The simplest of these involve using
wildcards in certain fields of the method signature. For example, the
pointcut
+[source, java]
....
call(void Figure.make*(..))
....
@@ -211,16 +216,18 @@ picks out each join point that's a call to a void method defined on
parameters. In our system, this picks out calls to the factory methods
`makePoint` and `makeLine`. The pointcut
+[source, java]
....
call(public * Figure.* (..))
....
-picks out each call to `Figure`'s public methods.
+picks out each call to ``Figure``'s public methods.
But wildcards aren't the only properties AspectJ supports. Another
pointcut, `cflow`, identifies join points based on whether they occur in
the dynamic context of other join points. So
+[source, java]
....
cflow(move())
....
@@ -245,6 +252,7 @@ For example, before advice on a method call join point runs before the
actual method starts running, just after the arguments to the method
call are evaluated.
+[source, java]
....
before(): move() {
System.out.println("about to move");
@@ -260,6 +268,7 @@ of after advice: `after returning`, `after
throwing`, and plain `after` (which runs after returning _or_
throwing, like Java's `finally`).
+[source, java]
....
after() returning: move() {
System.out.println("just successfully moved");
@@ -280,6 +289,7 @@ An advice declaration has a parameter list (like a method) that gives
names to all the pieces of context that it uses. For example, the after
advice
+[source, java]
....
after(FigureElement fe, int x, int y) returning:
...SomePointcut... {
@@ -288,10 +298,11 @@ after(FigureElement fe, int x, int y) returning:
....
uses three pieces of exposed context, a `FigureElement` named fe, and
-two `int`s named x and y.
+two ``int``s named x and y.
The body of the advice uses the names just like method parameters, so
+[source, java]
....
after(FigureElement fe, int x, int y) returning:
...SomePointcut... {
@@ -303,6 +314,7 @@ The advice's pointcut publishes the values for the advice's arguments.
The three primitive pointcuts `this`, `target` and `args` are used to
publish these values. So now we can write the complete piece of advice:
+[source, java]
....
after(FigureElement fe, int x, int y) returning:
call(void FigureElement.setXY(int, int))
@@ -326,6 +338,7 @@ named pointcut is used (by advice, or in another named pointcut), it
publishes its context by name just like the `this`, `target` and `args`
pointcut. So another way to write the above advice is
+[source, java]
....
pointcut setXY(FigureElement fe, int x, int y):
call(void FigureElement.setXY(int, int))
@@ -360,8 +373,9 @@ Suppose we want to have `Screen` objects observe changes to `Point`
objects, where `Point` is an existing class. We can implement this by
writing an aspect declaring that the class Point `Point` has an instance
field, `observers`, that keeps track of the `Screen` objects that are
-observing `Point`s.
+observing ``Point``s.
+[source, java]
....
aspect PointObserving {
private Vector Point.observers = new Vector();
@@ -373,6 +387,7 @@ The `observers` field is private, so only `PointObserving` can see it.
So observers are added or removed with the static methods `addObserver`
and `removeObserver` on the aspect.
+[source, java]
....
aspect PointObserving {
private Vector Point.observers = new Vector();
@@ -391,6 +406,7 @@ Along with this, we can define a pointcut `changes` that defines what we
want to observe, and the after advice defines what we want to do when we
observe a change.
+[source, java]
....
aspect PointObserving {
private Vector Point.observers = new Vector();
@@ -417,7 +433,7 @@ aspect PointObserving {
}
....
-Note that neither `Screen`'s nor `Point`'s code has to be modified, and
+Note that neither ``Screen``'s nor ``Point``'s code has to be modified, and
that all the changes needed to support this new capability are local to
this aspect.
@@ -435,6 +451,7 @@ aspect instances. By default, each aspect is a singleton, so one aspect
instance is created. This means that advice may use non-static fields of
the aspect, if it needs to keep state around:
+[source, java]
....
aspect Logging {
OutputStream logStream = System.err;
@@ -471,6 +488,7 @@ workings of a program. It is a simple tracing aspect that prints a
message at specified method calls. In our figure editor example, one
such aspect might simply trace whenever points are drawn.
+[source, java]
....
aspect SimpleTracing {
pointcut tracedCall():
@@ -487,6 +505,7 @@ advice bodies this variable is bound to an object that describes the
current join point. The effect of this code is to print a line like the
following every time a figure element receives a `draw` method call:
+[source, text]
....
Entering: call(void FigureElement.draw(GraphicsContext))
....
@@ -529,6 +548,7 @@ For example, the following aspect counts the number of calls to the
methods of a `Point` that happen within the control flow of those calls
to `rotate`:
+[source, java]
....
aspect SetsInRotateCounting {
int rotateCount = 0;
@@ -589,6 +609,7 @@ properly do the work they are supposed to.
AspectJ makes it possible to implement pre- and post-condition testing
in modular form. For example, this code
+[source, java]
....
aspect PointBoundsChecking {
@@ -636,6 +657,7 @@ the constraint that only the well-known factory methods can add an
element to the registry of figure elements. Enforcing this constraint
ensures that no figure element is added to the registry more than once.
+[source, java]
....
aspect RegistrationProtection {
@@ -662,6 +684,7 @@ This advice throws a runtime exception at certain join points, but
AspectJ can do better. Using the `declare error` form, we can have the
_compiler_ signal the error.
+[source, java]
....
aspect RegistrationProtection {
@@ -722,6 +745,7 @@ state of the dirty flag and resets it to false. The pointcut `move`
captures all the method calls that can move a figure element. The after
advice on `move` sets the dirty flag whenever an object moves.
+[source, java]
....
aspect MoveTracking {
private static boolean dirty = false;
@@ -807,6 +831,7 @@ modular way. The following code adds after advice that runs only when
the factory methods of `Figure` are called in the control flow of a
method on a `ColorControllingClient`.
+[source, java]
....
aspect ColorControl {
pointcut CCClientCflow(ColorControllingClient client):
@@ -841,6 +866,7 @@ captures the public method calls of the package, and the after advice
runs whenever one of those calls throws an Error. The advice logs that
Error and then the throw resumes.
+[source, java]
....
aspect PublicErrorLogging {
Log log = new Log();
@@ -861,6 +887,7 @@ outermost call into the `com.bigboxco` package and the re-entrant call.
The `cflow` primitive pointcut can be used in a nice way to exclude
these re-entrant calls:
+[source, java]
....
after() throwing (Error e):
publicMethodCall() && !cflow(publicMethodCall()) {
@@ -874,6 +901,7 @@ individual methods handle each of the different kinds of elements that
must be parsed. They have names like `parseMethodDec`, `parseThrows`,
and `parseExpr`.
+[source, java]
....
aspect ContextFilling {
pointcut parse(JavaParser jp):
diff --git a/docs/progGuideDB/idioms.adoc b/docs/progGuideDB/idioms.adoc
index 9bc16c081..8e5f6e43e 100644
--- a/docs/progGuideDB/idioms.adoc
+++ b/docs/progGuideDB/idioms.adoc
@@ -11,6 +11,7 @@ Here's an example of how to enfore a rule that code in the java.sql
package can only be used from one particular package in your system.
This doesn't require any access to code in the java.sql package.
+[source, java]
....
/* Any call to methods or constructors in java.sql */
pointcut restrictedCall():
@@ -27,6 +28,7 @@ declare error: restrictedCall() && illegalSource():
Any call to an instance of a subtype of AbstractFacade whose class is
not exactly equal to AbstractFacade:
+[source, java]
....
pointcut nonAbstract(AbstractFacade af):
call(* *(..))
@@ -37,6 +39,7 @@ pointcut nonAbstract(AbstractFacade af):
If AbstractFacade is an abstract class or an interface, then every
instance must be of a subtype and you can replace this with:
+[source, java]
....
pointcut nonAbstract(AbstractFacade af):
call(* *(..))
@@ -46,6 +49,7 @@ pointcut nonAbstract(AbstractFacade af):
Any call to a method which is defined by a subtype of AbstractFacade,
but which isn't defined by the type AbstractFacade itself:
+[source, java]
....
pointcut callToUndefinedMethod():
call(* AbstractFacade+.*(..))
@@ -55,6 +59,7 @@ pointcut callToUndefinedMethod():
The execution of a method that is defined in the source code for a type
that is a subtype of AbstractFacade but not in AbstractFacade itself:
+[source, java]
....
pointcut executionOfUndefinedMethod():
execution(* *(..))
diff --git a/docs/progGuideDB/implementation.adoc b/docs/progGuideDB/implementation.adoc
index a34324d5f..f7a8f7c7b 100644
--- a/docs/progGuideDB/implementation.adoc
+++ b/docs/progGuideDB/implementation.adoc
@@ -17,6 +17,7 @@ implementations should do tomorrow.
According to the AspectJ language semantics, the declaration
+[source, java]
....
before(): get(int Point.x) { System.out.println("got x"); }
....
@@ -128,6 +129,7 @@ source code. This means that there may be call join points to
`Class.forName` or `StringBuffer.append` from programs that do not, at
first glance, appear to contain such calls:
+[source, java]
....
class Test {
void main(String[] args) {
@@ -158,6 +160,7 @@ be the case. Before advice is allowed.
The second is that the control flow of a handler join point is not
picked out. For example, the following pointcut
+[source, java]
....
cflow(call(void foo()) || handler(java.io.IOException))
....
@@ -173,6 +176,7 @@ This does not restrict programs from placing before advice on handlers
inside _other_ control flows. This advice, for example, is perfectly
fine:
+[source, java]
....
before(): handler(java.io.IOException) && cflow(void parse()) {
System.out.println("about to handle an exception while parsing");
@@ -187,6 +191,7 @@ have fewer such restrictions.
The code for Java initializers, such as the assignment to the field d in
+[source, java]
....
class C {
double d = Math.sqrt(2);
@@ -203,6 +208,7 @@ a super-constructor (as opposed to a `this` constructor), the target
type's initialization code will _not_ be run when that inter-type
constructor is called.
+[source, java]
....
aspect A {
C.new(Object o) {} // implicitly calls super()
diff --git a/docs/progGuideDB/language.adoc b/docs/progGuideDB/language.adoc
index f48cc4290..3aeb5eebd 100644
--- a/docs/progGuideDB/language.adoc
+++ b/docs/progGuideDB/language.adoc
@@ -24,30 +24,31 @@ exposed to the new terminology introduced by AspectJ.
Here's an example of an aspect definition in AspectJ:
-....
- 1 aspect FaultHandler {
- 2
- 3 private boolean Server.disabled = false;
- 4
- 5 private void reportFault() {
- 6 System.out.println("Failure! Please fix it.");
- 7 }
- 8
- 9 public static void fixServer(Server s) {
-10 s.disabled = false;
-11 }
-12
-13 pointcut services(Server s): target(s) && call(public * *(..));
-14
-15 before(Server s): services(s) {
-16 if (s.disabled) throw new DisabledException();
-17 }
-18
-19 after(Server s) throwing (FaultException e): services(s) {
-20 s.disabled = true;
-21 reportFault();
-22 }
-23 }
+[source, java]
+....
+/*01*/ aspect FaultHandler {
+/*02*/
+/*03*/ private boolean Server.disabled = false;
+/*04*/
+/*05*/ private void reportFault() {
+/*06*/ System.out.println("Failure! Please fix it.");
+/*07*/ }
+/*08*/
+/*09*/ public static void fixServer(Server s) {
+/*10*/ s.disabled = false;
+/*11*/ }
+/*12*/
+/*13*/ pointcut services(Server s): target(s) && call(public * *(..));
+/*14*/
+/*15*/ before(Server s): services(s) {
+/*16*/ if (s.disabled) throw new DisabledException();
+/*17*/ }
+/*18*/
+/*19*/ after(Server s) throwing (FaultException e): services(s) {
+/*20*/ s.disabled = true;
+/*21*/ reportFault();
+/*22*/ }
+/*23*/ }
....
The `FaultHandler` consists of one inter-type field on `Server` (line
@@ -69,6 +70,7 @@ invocations and executions, the handling of exceptions, field
assignments and accesses, etc. Take, for example, the pointcut
definition in line 13:
+[source, java]
....
pointcut services(Server s): target(s) && call(public * *(..))
....
@@ -114,6 +116,7 @@ define aspect implementation that runs at join points picked out by the
pointcut. For example, the advice in lines 15-17 specifies that the
following piece of code
+[source, java]
....
{
if (s.disabled) throw new DisabledException();
@@ -128,6 +131,7 @@ corresponding methods are executed.
The advice in lines 19-22 defines another piece of implementation that
is executed on the same pointcut:
+[source, java]
....
{
s.disabled = true;
@@ -148,6 +152,7 @@ this guide.
Consider the following Java class:
+[source, java]
....
class Point {
private int x, y;
@@ -166,6 +171,7 @@ In order to get an intuitive understanding of AspectJ's join points and
pointcuts, let's go back to some of the basic principles of Java.
Consider the following a method declaration in class Point:
+[source, java]
....
void setX(int x) { this.x = x; }
....
@@ -192,6 +198,7 @@ complete listing.)
Pointcuts pick out these join points. For example, the pointcut
+[source, java]
....
pointcut setter(): target(Point) &&
(call(void setX(int)) ||
@@ -201,6 +208,7 @@ pointcut setter(): target(Point) &&
picks out each call to `setX(int)` or `setY(int)` when called on an
instance of `Point`. Here's another example:
+[source, java]
....
pointcut ioHandler(): within(MyClass) && handler(IOException);
....
@@ -230,7 +238,7 @@ when the target object is of type `SomeType`::
`target(SomeType)`
when the executing code belongs to class `MyClass`::
`within(MyClass)`
-when the join point is in the control flow of a call to a `Test`'s
+when the join point is in the control flow of a call to a ``Test``'s
no-argument `main` method::
`cflow(call(void Test.main()))`
@@ -256,9 +264,9 @@ such `set` method; this pointcut picks out calls to all of them.
means (1) the execution of any method with no parameters that returns an
`int`, (2) the call to any `setY` method that takes a `long` as an
argument, regardless of return type or declaring type, (3) the call to
-any of `Point`'s `setY` methods that take an `int` as an argument,
+any of ``Point``'s `setY` methods that take an `int` as an argument,
regardless of return type, and (4) the call to any classes' constructor,
-so long as it takes exactly two `int`s as arguments.
+so long as it takes exactly two ``int``s as arguments.
* You can compose pointcuts. For example,
[arabic]
. `target(Point) && call(int *())`
@@ -270,7 +278,7 @@ so long as it takes exactly two `int`s as arguments.
+
means (1) any call to an `int` method with no arguments on an instance
of `Point`, regardless of its name, (2) any call to any method where the
-call is made from the code in `Point`'s or `Line`'s type declaration,
+call is made from the code in ``Point``'s or ``Line``'s type declaration,
(3) the execution of any constructor taking exactly one `int` argument,
regardless of where the call is made from, and (4) any method call to an
`int` method when the executing object is any type except `Point`.
@@ -286,12 +294,13 @@ non-static method, and (3) any execution of a public, non-static method.
* Pointcuts can also deal with interfaces. For example, given the
interface
+
+[source, java]
....
interface MyInterface { ... }
....
+
the pointcut `call(* MyInterface.*(..))` picks out any call to a method
-in `MyInterface`'s signature -- that is, any method defined by
+in ``MyInterface``'s signature -- that is, any method defined by
`MyInterface` or inherited by one of its a supertypes.
[[call-vs-execution]]
@@ -339,6 +348,7 @@ primitive pointcuts like `cflow` and `cflowbelow`. Here's an example:
`cflow(P)` picks out each join point in the control flow of the join
points picked out by <P>. So, pictorially:
+[source, text]
....
P ---------------------
\
@@ -350,6 +360,7 @@ What does `cflow(P) &&
cflow(Q)` pick out? Well, it picks out each join point that is
in both the control flow of <P> and in the control flow of <Q>. So...
+[source, text]
....
P ---------------------
\
@@ -370,6 +381,7 @@ But what does `cflow(P
&& Q)` mean? Well, it means the control flow of those join
points that are both picked out by <P> and picked out by <Q>.
+[source, text]
....
P && Q -------------------
\
@@ -384,6 +396,7 @@ control flow of `(P &&
Here's some code that expresses this.
+[source, java]
....
public class Test {
public static void main(String[] args) {
@@ -422,6 +435,7 @@ for more details.)
Consider again the first pointcut definition in this chapter:
+[source, java]
....
pointcut setter(): target(Point) &&
(call(void setX(int)) ||
@@ -435,6 +449,7 @@ side. An empty parameter list means that none of the context from the
join points is published from this pointcut. But consider another
version of version of this pointcut definition:
+[source, java]
....
pointcut setter(Point p): target(p) &&
(call(void setX(int)) ||
@@ -452,6 +467,7 @@ matched join point.
Here's another example that illustrates the flexible mechanism for
defining pointcut parameters:
+[source, java]
....
pointcut testEquality(Point p): target(Point) &&
args(p) &&
@@ -464,10 +480,11 @@ access to a `Point` from each join point. But in this case, looking at
the right-hand side we find that the object named in the parameters is
not the target `Point` object that receives the call; it's the argument
(also of type `Point`) passed to the `equals` method when some other
-`Point` is the target. If we wanted access to both `Point`s, then the
+`Point` is the target. If we wanted access to both ``Point``s, then the
pointcut definition that would expose target `Point p1` and argument
`Point p2` would be
+[source, java]
....
pointcut testEquality(Point p1, Point p2): target(p1) &&
args(p2) &&
@@ -476,6 +493,7 @@ pointcut testEquality(Point p1, Point p2): target(p1) &&
Let's look at another variation of the `setters` pointcut:
+[source, java]
....
pointcut setter(Point p, int newval): target(p) &&
args(newval) &&
@@ -493,6 +511,7 @@ important rule is that all the pointcut parameters must be bound at
every join point picked out by the pointcut. So, for example, the
following pointcut definition will result in a compilation error:
+[source, java]
....
pointcut badPointcut(Point p1, Point p2):
(target(p1) && call(void setX(int))) ||
@@ -512,6 +531,7 @@ operations to their `Partner` objects. The aspect `HandleLiveness`
ensures that, before the delegations, the partner exists and is alive,
or else it throws an exception.
+[source, java]
....
class Handle {
Partner partner = new Partner();
@@ -594,6 +614,7 @@ given either by named pointcuts (like the ones you've seen above) or by
anonymous pointcuts. Here is an example of an advice on a named
pointcut:
+[source, java]
....
pointcut setter(Point p1, int newval): target(p1) && args(newval)
(call(void setX(int) ||
@@ -607,6 +628,7 @@ before(Point p1, int newval): setter(p1, newval) {
And here is exactly the same example, but using an anonymous pointcut:
+[source, java]
....
before(Point p1, int newval): target(p1) && args(newval)
(call(void setX(int)) ||
@@ -621,6 +643,7 @@ Here are examples of the different advice:
This before advice runs just before the join points picked out by the
(anonymous) pointcut:
+[source, java]
....
before(Point p, int x): target(p) && args(x) && call(void setX(int)) {
if (!p.assertX(x)) return;
@@ -631,6 +654,7 @@ This after advice runs just after each join point picked out by the
(anonymous) pointcut, regardless of whether it returns normally or
throws an exception:
+[source, java]
....
after(Point p, int x): target(p) && args(x) && call(void setX(int)) {
if (!p.assertX(x)) throw new PostConditionViolation();
@@ -642,6 +666,7 @@ by the (anonymous) pointcut, but only if it returns normally. The return
value can be accessed, and is named `x` here. After the advice runs, the
return value is returned:
+[source, java]
....
after(Point p) returning(int x): target(p) && call(int getX()) {
System.out.println("Returning int value " + x + " for p = " + p);
@@ -653,6 +678,7 @@ the (anonymous) pointcut, but only when it throws an exception of type
`Exception`. Here the exception value can be accessed with the name `e`.
The advice re-raises the exception after it's done:
+[source, java]
....
after() throwing(Exception e): target(Point) && call(void setX(int)) {
System.out.println(e);
@@ -663,6 +689,7 @@ This around advice traps the execution of the join point; it runs
_instead_ of the join point. The original action associated with the
join point can be invoked through the special `proceed` call:
+[source, java]
....
void around(Point p, int x): target(p)
&& args(x)
@@ -683,6 +710,7 @@ class. Here are examples of some such inter-type declarations:
This declares that each `Server` has a `boolean` field named `disabled`,
initialized to `false`:
+[source, java]
....
private boolean Server.disabled = false;
....
@@ -696,6 +724,7 @@ another aspect) there won't be a name collision, since no reference to
This declares that each `Point` has an `int` method named `getX` with no
arguments that returns whatever `this.x` is:
+[source, java]
....
public int Point.getX() { return this.x; }
....
@@ -707,6 +736,7 @@ conflict.
This publically declares a two-argument constructor for `Point`:
+[source, java]
....
public Point.new(int x, int y) { this.x = x; this.y = y; }
....
@@ -714,6 +744,7 @@ public Point.new(int x, int y) { this.x = x; this.y = y; }
This publicly declares that each `Point` has an `int` field named `x`,
initialized to zero:
+[source, java]
....
public int Point.x = 0;
....
@@ -724,6 +755,7 @@ has a field named `x` (defined by `Point` or by another aspect).
This declares that the `Point` class implements the `Comparable`
interface:
+[source, java]
....
declare parents: Point implements Comparable;
....
@@ -734,6 +766,7 @@ required by `Comparable`.
This declares that the `Point` class extends the `GeometricObject`
class.
+[source, java]
....
declare parents: Point extends GeometricObject;
....
@@ -741,6 +774,7 @@ declare parents: Point extends GeometricObject;
An aspect can have several inter-type declarations. For example, the
following declarations
+[source, java]
....
public String Point.name;
public void Point.setName(String name) { this.name = name; }
@@ -754,6 +788,7 @@ An inter-type member can only have one target type, but often you may
wish to declare the same member on more than one type. This can be done
by using an inter-type member in combination with a private interface:
+[source, java]
....
aspect A {
private interface HasName {}
@@ -782,18 +817,20 @@ declarations in addition to public inter-type declarations. Private
means private in relation to the aspect, not necessarily the target
type. So, if an aspect makes a private inter-type declaration of a field
+[source, java]
....
private int Foo.x;
....
-Then code in the aspect can refer to `Foo`'s `x` field, but nobody else
+Then code in the aspect can refer to ``Foo``'s `x` field, but nobody else
can. Similarly, if an aspect makes a package-protected introduction,
+[source, java]
....
- int Foo.x;
+int Foo.x;
....
-then everything in the aspect's package (which may or may not be `Foo`'s
+then everything in the aspect's package (which may or may not be ``Foo``'s
package) can access `x`.
==== Example: `PointAssertions`
@@ -806,6 +843,7 @@ other parts of the program (including the code in `Point`) have no
business accessing the assert methods. Only the code inside of the
aspect can call those methods.
+[source, java]
....
class Point {
int x, y;
@@ -856,6 +894,7 @@ One way to use it is simply to print it out. Like all Java objects,
`thisJoinPoint` has a `toString()` method that makes quick-and-dirty
tracing easy:
+[source, java]
....
aspect TraceNonStaticMethods {
before(Point p): target(p) && call(* *(..)) {
@@ -868,6 +907,7 @@ The type of `thisJoinPoint` includes a rich reflective class hierarchy
of signatures, and can be used to access both static and dynamic
information about join points such as the arguments of the join point:
+[source, java]
....
thisJoinPoint.getArgs()
....
@@ -876,6 +916,7 @@ In addition, it holds an object consisting of all the static information
about the join point such as corresponding line number and static
signature:
+[source, java]
....
thisJoinPoint.getStaticPart()
....
@@ -888,6 +929,7 @@ necessary when using `thisJoinPoint` directly.
It is always the case that
+[source, java]
....
thisJoinPointStaticPart == thisJoinPoint.getStaticPart()
@@ -903,8 +945,9 @@ but it is not the current but the enclosing join point. So, for example,
it is possible to print out the calling source location (if available)
with
+[source, java]
....
- before() : execution (* *(..)) {
- System.err.println(thisEnclosingJoinPointStaticPart.getSourceLocation())
- }
+before() : execution (* *(..)) {
+ System.err.println(thisEnclosingJoinPointStaticPart.getSourceLocation())
+}
....
diff --git a/docs/progGuideDB/pitfalls.adoc b/docs/progGuideDB/pitfalls.adoc
index b1769ce26..0bbe6f5f5 100644
--- a/docs/progGuideDB/pitfalls.adoc
+++ b/docs/progGuideDB/pitfalls.adoc
@@ -11,6 +11,7 @@ surprising behavior and how to understand them.
Here is a Java program with peculiar behavior
+[source, java]
....
public class Main {
public static void main(String[] args) {
@@ -39,6 +40,7 @@ the completely silent abort.
The following short aspect will also generate this behavior:
+[source, java]
....
aspect A {
before(): call(* *(..)) { System.out.println("before"); }
@@ -50,6 +52,7 @@ Why? Because the call to println is also a call matched by the pointcut
`call (* *(..))`. We get no output because we used simple after()
advice. If the aspect were changed to
+[source, java]
....
aspect A {
before(): call(* *(..)) { System.out.println("before"); }
@@ -65,6 +68,7 @@ There's a simple idiom to use if you ever have a worry that your advice
might apply in this way. Just restrict the advice from occurring in join
points caused within the aspect. So:
+[source, java]
....
aspect A {
before(): call(* *(..)) && !within(A) { System.out.println("before"); }
@@ -75,6 +79,7 @@ aspect A {
Other solutions might be to more closely restrict the pointcut in other
ways, for example:
+[source, java]
....
aspect A {
before(): call(* MyObject.*(..)) { System.out.println("before"); }
diff --git a/docs/progGuideDB/quickreference.adoc b/docs/progGuideDB/quickreference.adoc
index 01b152e31..6d8febc56 100644
--- a/docs/progGuideDB/quickreference.adoc
+++ b/docs/progGuideDB/quickreference.adoc
@@ -9,16 +9,16 @@
|*Methods and Constructors* |
|`call(Signature)` |every call to any method or constructor matching
-<Signature> at the call site
+`<Signature>` at the call site
|`execution(Signature)` |every execution of any method or constructor
-matching <Signature>
+matching `<Signature>`
|*Fields* |
-|`get(Signature)` |every reference to any field matching <Signature>
+|`get(Signature)` |every reference to any field matching `<Signature>`
-|`set(Signature)` |every assignment to any field matching <Signature>.
+|`set(Signature)` |every assignment to any field matching `<Signature>`.
The assigned value can be exposed with an `args` pointcut
|*Exception Handlers* |
@@ -37,12 +37,12 @@ pointcut
initializer for any type in <TypePattern>
|`initialization(Signature)` |every initialization of an object when the
-first constructor called in the type matches <Signature>, encompassing
+first constructor called in the type matches `<Signature>`, encompassing
the return from the super constructor call to the return of the
first-called constructor
|`preinitialization(Signature)` |every pre-initialization of an object
-when the first constructor called in the type matches <Signature>,
+when the first constructor called in the type matches `<Signature>`,
encompassing the entry of the first-called constructor to the call to
the super constructor
@@ -52,7 +52,7 @@ the super constructor
<TypePattern>
|`withincode(Signature)` |every join point from code defined in a method
-or constructor matching <Signature>
+or constructor matching `<Signature>`
|===
[[quick-typePatterns]]
@@ -62,290 +62,118 @@ A type pattern is one of
[cols=",",]
|===
-|<TypeNamePattern> |all types in <TypeNamePattern>
+|*Type pattern* |
-|<SubtypePattern> |all types in <SubtypePattern>, a pattern with a +.
+|`<TypeNamePattern>` |all types in `<TypeNamePattern>`
-|<ArrayTypePattern> |all types in <ArrayTypePattern>, a pattern with one
-or more []s.
+|`<SubtypePattern>` |all types in `<SubtypePattern>`, a pattern with a `+`
+
+|`<ArrayTypePattern>` |all types in `<ArrayTypePattern>`, a pattern with one or more ``[]``s.
|`!TypePattern` |all types not in <TypePattern>
-|`TypePattern0
- && TypePattern1` |all types in both <TypePattern0> and
-<TypePattern1>
+|`TypePattern0 && TypePattern1` |all types in both `<TypePattern0>` and `<TypePattern1>`
-|`TypePattern0 || TypePattern1` |all types in either <TypePattern0> or
-<TypePattern1>
+|`TypePattern0 \|\| TypePattern1` |all types in either `<TypePattern0>` or `<TypePattern1>`
-|`( TypePattern )` |all types in <TypePattern>
+|`( TypePattern )` |all types in `<TypePattern>`
|===
-where <TypeNamePattern> can either be a plain type name, the wildcard
-`*` (indicating all types), or an identifier with embedded `*` and `..`
+where `<TypeNamePattern>` can either be a plain type name, the wildcard
+`\*` (indicating all types), or an identifier with embedded `*` and `..`
wildcards.
An embedded `*` in an identifier matches any sequence of characters, but
-does not match the package (or inner-type) separator ".".
+does not match the package (or inner-type) separator `.`.
An embedded `..` in an identifier matches any sequence of characters
-that starts and ends with the package (or inner-type) separator ".".
+that starts and ends with the package (or inner-type) separator `.`.
[[quick-advice]]
=== Advice
Each piece of advice is of the form
-____
-[ strictfp ]
-
-AdviceSpec
-
-[ throws
-
-TypeList
-
-] :
-
-Pointcut
+[source, text]
+....
+[ strictfp ] AdviceSpec [ throws TypeList ] : Pointcut { Body }
+....
-\{
+where `<AdviceSpec>` is one of
-Body
-
-}
-____
-
-where <AdviceSpec> is one of
-
-`before( Formals ) `::
+`before( Formals )`::
runs before each join point
-`after( Formals ) returning
- [ ( Formal ) ] `::
+`after( Formals ) returning [ ( Formal ) ]`::
runs after each join point that returns normally. The optional formal
gives access to the returned value
-`after( Formals ) throwing [
- ( Formal ) ] `::
- runs after each join point that throws a
- +
- Throwable
- +
- . If the optional formal is present, runs only after each join point
- that throws a
- +
- Throwable
- +
- of the type of
- +
- Formal
- +
- , and
- +
- Formal
- +
- gives access to the
- +
- Throwable
- +
- exception value
-`after( Formals ) `::
+`after( Formals ) throwing [ ( Formal ) ]`::
+ runs after each join point that throws a `Throwable`.
+ If the optional formal is present, runs only after each join point
+ that throws a `Throwable` of the type of `Formal`, and `Formal` gives access to the
+ `Throwable` exception value
+`after( Formals )`::
runs after each join point regardless of whether it returns normally
- or throws a
- +
- Throwable
-`Type
- around( Formals ) `::
+ or throws a `Throwable`
+`Type around( Formals )`::
runs in place of each join point. The join point can be executed by
- calling
- +
- proceed
- +
- , which takes the same number and types of arguments as the around
+ calling `proceed`, which takes the same number and types of arguments as the around
advice.
Three special variables are available inside of advice bodies:
`thisJoinPoint`::
- an object of type
- +
- org.aspectj.lang.JoinPoint
- +
- representing the join point at which the advice is executing.
+ an object of type `org.aspectj.lang.JoinPoint` representing the join point
+ at which the advice is executing
`thisJoinPointStaticPart`::
- equivalent to
- +
- thisJoinPoint.getStaticPart()
- +
- , but may use fewer runtime resources.
+ equivalent to `thisJoinPoint.getStaticPart()`, but may use fewer runtime resources
`thisEnclosingJoinPointStaticPart`::
- the static part of the dynamically enclosing join point.
+ the static part of the dynamically enclosing join point
[[quick-interType]]
=== Inter-type member declarations
Each inter-type member is one of
-`
- Modifiers ReturnType OnType . Id
- ( Formals )
- [ throws TypeList ]
- { Body }
- `::
- a method on
- +
- OnType
- +
- .
-`
- abstract Modifiers ReturnType OnType . Id
- ( Formals )
- [ throws TypeList ] ;
- `::
- an abstract method on
- +
- OnType
- +
- .
-`
- Modifiers OnType . new
- ( Formals )
- [ throws TypeList ]
- { Body }
- `::
- a constructor on
- +
- OnType
- +
- .
-`
- Modifiers Type OnType . Id
- [ = Expression ] ;
- `::
- a field on
- +
- OnType
- +
- .
+`Modifiers ReturnType OnType . Id ( Formals ) [ throws TypeList ] { Body }`::
+ a method on `OnType`
+`abstract Modifiers ReturnType OnType . Id ( Formals ) [ throws TypeList ] ;`::
+ an abstract method on `OnType`
+`Modifiers OnType . new ( Formals ) [ throws TypeList ] { Body }`::
+ a constructor on `OnType`
+`Modifiers Type OnType . Id [ = Expression ] ;`::
+ a field on `OnType`
[[quick-other]]
=== Other declarations
-`
- declare parents :
- TypePattern extends
- Type ;
- `::
- the types in
- +
- TypePattern
- +
- extend
- +
- Type
- +
- .
-`
- declare parents : TypePattern
- implements TypeList ;
- `::
- the types in
- +
- TypePattern
- +
- implement the types in
- +
- TypeList
- +
- .
-`
- declare warning : Pointcut :
- String ;
- `::
- if any of the join points in
- +
- Pointcut
- +
- possibly exist in the program, the compiler emits the warning
- +
- String
- +
- .
-`
- declare error : Pointcut :
- String ;
- `::
- if any of the join points in
- +
- Pointcut
- +
- could possibly exist in the program, the compiler emits the error
- +
- String
- +
- .
-`
- declare soft :
- Type :
- Pointcut ;
- `::
- any
- +
- Type
- +
- exception that gets thrown at any join point picked out by
- +
- Pointcut
- +
- is wrapped in
- +
- org.aspectj.lang.SoftException
- +
- .
-`
- declare precedence :
- TypePatternList ;
- `::
+`declare parents : TypePattern extends Type ;`::
+ the types in `TypePattern` extend `Type`
+`declare parents : TypePattern implements TypeList ;`::
+ the types in `TypePattern` implement the types in `TypeList`
+`declare warning : Pointcut : String ;`::
+ if any of the join points in `Pointcut` possibly exist in the program,
+ the compiler emits the warning `String`
+`declare error : Pointcut : String ;`::
+ if any of the join points in `Pointcut` could possibly exist in the program,
+ the compiler emits the error `String`
+`declare soft : Type : Pointcut ;`::
+ any `Type` exception that gets thrown at any join point picked out by `Pointcut`
+ is wrapped in `org.aspectj.lang.SoftException`
+`declare precedence : TypePatternList ;`::
at any join point where multiple pieces of advice apply, the advice
- precedence at that join point is in
- +
- TypePatternList
- +
- order.
+ precedence at that join point is in `TypePatternList` order
[[quick-aspectAssociations]]
=== Aspects
Each aspect is of the form
-____
-[ privileged ]
-
-Modifiers
-
-aspect
-
-Id
-
-[ extends
-
-Type
-
-] [ implements
-
-TypeList
-
-] [
-
-PerClause
-
-] \{
-
-Body
-
-}
-____
+[source, text]
+....
+[ privileged ] Modifiers aspect Id [ extends Type ] [ implements TypeList ] [ PerClause ] { Body }
+....
-where <PerClause> defines how the aspect is instantiated and associated
+where `<PerClause>` defines how the aspect is instantiated and associated
(`issingleton()` by default):
[cols=",,",options="header",]
@@ -355,18 +183,18 @@ where <PerClause> defines how the aspect is instantiated and associated
default. |`aspectOf()` at all join points
|`perthis(Pointcut)` |An instance is associated with each object that is
-the currently executing object at any join point in <Pointcut>.
+the currently executing object at any join point in `<Pointcut>`.
|`aspectOf(Object)` at all join points
|`pertarget(Pointcut)` |An instance is associated with each object that
-is the target object at any join point in <Pointcut>.
+is the target object at any join point in `<Pointcut>`.
|`aspectOf(Object)` at all join points
|`percflow(Pointcut)` |The aspect is defined for each entrance to the
-control flow of the join points defined by <Pointcut>. |`aspectOf()` at
+control flow of the join points defined by `<Pointcut>`. |`aspectOf()` at
join points in `cflow(Pointcut)`
|`percflowbelow(Pointcut)` |The aspect is defined for each entrance to
-the control flow below the join points defined by <Pointcut>.
+the control flow below the join points defined by `<Pointcut>`.
|`aspectOf()` at join points in `cflowbelow(Pointcut)`
|===
diff --git a/docs/progGuideDB/semantics.adoc b/docs/progGuideDB/semantics.adoc
index 1943aa609..aa46cf18d 100644
--- a/docs/progGuideDB/semantics.adoc
+++ b/docs/progGuideDB/semantics.adoc
@@ -63,11 +63,7 @@ Constructor call::
Constructor execution::
When the body of code for an actual constructor executes, after its
this or super constructor call. The object being constructed is the
- currently executing object, and so may be accessed with the
- +
- this
- +
- pointcut. The constructor execution join point for a constructor that
+ currently executing object, and so may be accessed with the `_this_` pointcut. The constructor execution join point for a constructor that
calls a super constructor also includes any non-static initializers of
enclosing class. No value is returned from a constructor execution
join point, so its return type is considered to be void.
@@ -80,15 +76,7 @@ Object pre-initialization::
This encompasses the time between the start of its first called
constructor and the start of its parent's constructor. Thus, the
execution of these join points encompass the join points of the
- evaluation of the arguments of
- +
- this()
- +
- and
- +
- super()
- +
- constructor calls. No value is returned from an object
+ evaluation of the arguments of `_this()_` and `_super()_` constructor calls. No value is returned from an object
pre-initialization join point, so its return type is considered to be
void.
Object initialization::
@@ -97,11 +85,7 @@ Object initialization::
and the return of its first called constructor. It includes all the
dynamic initializers and constructors used to create the object. The
object being constructed is the currently executing object, and so may
- be accessed with the
- +
- this
- +
- pointcut. No value is returned from a constructor execution join
+ be accessed with the `_this_` pointcut. No value is returned from a constructor execution join
point, so its return type is considered to be void.
Field reference::
When a non-constant field is referenced. [Note that references to
@@ -180,219 +164,84 @@ build up other pointcuts. The primitive pointcuts and combinators
provided by the language are:
`call(MethodPattern)`::
- Picks out each method call join point whose signature matches
- +
- MethodPattern
- +
- .
+ Picks out each method call join point whose signature matches `_MethodPattern_`.
`execution(MethodPattern)`::
- Picks out each method execution join point whose signature matches
- +
- MethodPattern
- +
- .
+ Picks out each method execution join point whose signature matches `_MethodPattern_`.
`get(FieldPattern)`::
- Picks out each field reference join point whose signature matches
- +
- FieldPattern
- +
- . [Note that references to constant fields (static final fields bound
+ Picks out each field reference join point whose signature matches `_FieldPattern_`. [Note that references to constant fields (static final fields bound
to a constant string object or primitive value) are not join points,
since Java requires them to be inlined.]
`set(FieldPattern)`::
- Picks out each field set join point whose signature matches
- +
- FieldPattern
- +
- . [Note that the initializations of constant fields (static final
+ Picks out each field set join point whose signature matches `_FieldPattern_`. [Note that the initializations of constant fields (static final
fields where the initializer is a constant string object or primitive
value) are not join points, since Java requires their references to be
inlined.]
`call(ConstructorPattern)`::
- Picks out each constructor call join point whose signature matches
- +
- ConstructorPattern
- +
- .
+ Picks out each constructor call join point whose signature matches `_ConstructorPattern_`.
`execution(ConstructorPattern)`::
Picks out each constructor execution join point whose signature
- matches
- +
- ConstructorPattern
- +
- .
+ matches `_ConstructorPattern_`.
`initialization(ConstructorPattern)`::
Picks out each object initialization join point whose signature
- matches
- +
- ConstructorPattern
- +
- .
+ matches `_ConstructorPattern_`.
`preinitialization(ConstructorPattern)`::
Picks out each object pre-initialization join point whose signature
- matches
- +
- ConstructorPattern
- +
- .
+ matches `_ConstructorPattern_`.
`staticinitialization(TypePattern)`::
Picks out each static initializer execution join point whose signature
- matches
- +
- TypePattern
- +
- .
+ matches `_TypePattern_`.
`handler(TypePattern)`::
- Picks out each exception handler join point whose signature matches
- +
- TypePattern
- +
- .
+ Picks out each exception handler join point whose signature matches `_TypePattern_`.
`adviceexecution()`::
Picks out all advice execution join points.
`within(TypePattern)`::
Picks out each join point where the executing code is defined in a
- type matched by
- +
- TypePattern
- +
- .
+ type matched by `_TypePattern_`.
`withincode(MethodPattern)`::
Picks out each join point where the executing code is defined in a
- method whose signature matches
- +
- MethodPattern
- +
- .
+ method whose signature matches `_MethodPattern_`.
`withincode(ConstructorPattern)`::
Picks out each join point where the executing code is defined in a
- constructor whose signature matches
- +
- ConstructorPattern
- +
- .
+ constructor whose signature matches `_ConstructorPattern_`.
`cflow(Pointcut)`::
- Picks out each join point in the control flow of any join point
- +
- P
- +
- picked out by
- +
- Pointcut
- +
- , including
- +
- P
- +
- itself.
+ Picks out each join point in the control flow of any join point `_P_` picked out by `_Pointcut_` , including `_P_` itself.
`cflowbelow(Pointcut)`::
- Picks out each join point in the control flow of any join point
- +
- P
- +
- picked out by
- +
- Pointcut
- +
- , but not
- +
- P
- +
- itself.
+ Picks out each join point in the control flow of any join point `_P_` picked out by `_Pointcut_`, but not `_P_` itself.
`this(Type or Id)`::
Picks out each join point where the currently executing object (the
- object bound to
- +
- this
- +
- ) is an instance of
- +
- Type
- +
- , or of the type of the identifier
- +
- Id
- +
- (which must be bound in the enclosing advice or pointcut definition).
+ object bound to `_this_`) is an instance of `_Type_` , or of the type of the identifier `_Id_` (which must be bound in the enclosing advice or pointcut definition).
Will not match any join points from static contexts.
`target(Type or Id)`::
Picks out each join point where the target object (the object on which
- a call or field operation is applied to) is an instance of
- +
- Type
- +
- , or of the type of the identifier
- +
- Id
- +
- (which must be bound in the enclosing advice or pointcut definition).
+ a call or field operation is applied to) is an instance of `_Type_` , or of the type of the identifier `_Id_` (which must be bound in the enclosing advice or pointcut definition).
Will not match any calls, gets, or sets of static members.
`args(Type or Id, ...)`::
Picks out each join point where the arguments are instances of the
- appropriate type (or type of the identifier if using that form). A
- +
- null
- +
- argument is matched iff the static type of the argument (declared
+ appropriate type (or type of the identifier if using that form). A `_null_` argument is matched iff the static type of the argument (declared
parameter type or field type) is the same as, or a subtype of, the
specified args type.
`PointcutId(TypePattern or Id, ...)`::
Picks out each join point that is picked out by the user-defined
- pointcut designator named by
- +
- PointcutId
- +
- .
+ pointcut designator named by `_PointcutId_` .
`if(BooleanExpression)`::
- Picks out each join point where the boolean expression evaluates to
- +
- true
- +
- . The boolean expression used can only access static members,
- parameters exposed by the enclosing pointcut or advice, and
- +
- thisJoinPoint
- +
- forms. In particular, it cannot call non-static methods on the aspect
+ Picks out each join point where the boolean expression evaluates to `_true_` . The boolean expression used can only access static members,
+ parameters exposed by the enclosing pointcut or advice, and `_thisJoinPoint_` forms. In particular, it cannot call non-static methods on the aspect
or use return values or exceptions exposed by after advice.
`! Pointcut`::
- Picks out each join point that is not picked out by
- +
- Pointcut
- +
- .
+ Picks out each join point that is not picked out by `_Pointcut_` .
`Pointcut0 && Pointcut1`::
- Picks out each join points that is picked out by both
- +
- Pointcut0
- +
- and
- +
- Pointcut1
- +
- .
+ Picks out each join points that is picked out by both `_Pointcut0_` and `_Pointcut1_` .
`Pointcut0 || Pointcut1`::
- Picks out each join point that is picked out by either pointcuts.
- +
- Pointcut0
- +
- or
- +
- Pointcut1
- +
- .
+ Picks out each join point that is picked out by either pointcuts. `_Pointcut0_` or `_Pointcut1_` .
`( Pointcut )`::
- Picks out each join points picked out by
- +
- Pointcut
- +
- .
+ Picks out each join points picked out by `_Pointcut_` .
==== Pointcut definition
Pointcuts are defined and named by the programmer with the `pointcut`
declaration.
+[source, java]
....
pointcut publicIntCall(int i):
call(public * *(int)) && args(i);
@@ -402,6 +251,7 @@ A named pointcut may be defined in either a class or aspect, and is
treated as a member of the class or aspect where it is found. As a
member, it may have an access modifier such as `public` or `private`.
+[source, java]
....
class C {
pointcut publicCall(int i):
@@ -418,6 +268,7 @@ Pointcuts that are not final may be declared abstract, and defined
without a body. Abstract pointcuts may only be declared within abstract
aspects.
+[source, java]
....
abstract aspect A {
abstract pointcut publicCall(int i);
@@ -426,6 +277,7 @@ abstract aspect A {
In such a case, an extending aspect may override the abstract pointcut.
+[source, java]
....
aspect B extends A {
pointcut publicCall(int i): call(public Foo.m(int)) && args(i);
@@ -444,6 +296,7 @@ is different than the scope of other members; the scope of other members
is the enclosing class _body_. This means that the following code is
legal:
+[source, java]
....
aspect B percflow(publicCall()) {
pointcut publicCall(): call(public Foo.m(int));
@@ -466,6 +319,7 @@ collection of types. The pointcut designators that allow this are
rather than a type does two things. First, it selects join points as
based on the type of the formal parameter. So the pointcut
+[source, java]
....
pointcut intArg(int i): args(i);
....
@@ -477,6 +331,7 @@ advice or pointcut.
Values can be exposed from named pointcuts as well, so
+[source, java]
....
pointcut publicCall(int x): call(public *.*(int)) && intArg(x);
pointcut intArg(int i): args(i);
@@ -489,6 +344,7 @@ There is one special case for this kind of exposure. Exposing an
argument of type Object will also match primitive typed arguments, and
expose a "boxed" version of the primitive. So,
+[source, java]
....
pointcut publicCall(): call(public *.*(..)) && args(Object);
....
@@ -496,6 +352,7 @@ pointcut publicCall(): call(public *.*(..)) && args(Object);
will pick out all unary methods that take, as their only argument,
subtypes of Object (i.e., not primitive types like `int`), but
+[source, java]
....
pointcut publicCall(Object o): call(public *.*(..)) && args(o);
....
@@ -507,6 +364,7 @@ argument was an `int`, then the value passed to advice will be of type
The "boxing" of the primitive value is based on the _original_ primitive
type. So in the following program
+[source, java]
....
public class InstanceOf {
@@ -569,6 +427,7 @@ field is being set to, so at a set join point, that value can be
accessed with an `args` pointcut. So an aspect guarding a static integer
variable x declared in type T might be written as
+[source, java]
....
aspect GuardedX {
static final int MAX_CHANGE = 100;
@@ -632,6 +491,7 @@ the exception being handled. That value can be accessed with an `args`
pointcut. So an aspect used to put `FooException` objects into some
normal form before they are handled could be written as
+[source, java]
....
aspect NormalizeFooException {
before(FooException e): handler(FooException) && args(e) {
@@ -650,6 +510,7 @@ of advice
This can be used, for example, to filter out any join point in the
control flow of advice from a particular aspect.
+[source, java]
....
aspect TraceStuff {
pointcut myAdvice(): adviceexecution() && within(TraceStuff);
@@ -719,6 +580,7 @@ Object). If it is the "*" wildcard, then any argument will match, and if
it is the special wildcard "..", then any number of arguments will
match, just like in signature patterns. So the pointcut
+[source, java]
....
args(int, .., String)
....
@@ -762,6 +624,7 @@ Anytime such state is accessed, it is accessed through the _most recent_
control flow that matched. So the "current arg" that would be printed by
the following program is zero, even though it is in many control flows.
+[source, java]
....
class Test {
public static void main(String[] args) {
@@ -842,6 +705,7 @@ false. Within this expression, the `thisJoinPoint` object is available.
So one (extremely inefficient) way of picking out all call join points
would be to use the pointcut
+[source, java]
....
if(thisJoinPoint.getKind().equals("call"))
....
@@ -922,6 +786,7 @@ while constructor declarations omit the return type and replace the
method name with the class name. The start of a particular method
declaration, in class `Test`, for example, might be
+[source, java]
....
class C {
public final void foo() throws ArrayOutOfBoundsException { ... }
@@ -931,12 +796,14 @@ class C {
In AspectJ, method signature patterns have all these, but most elements
can be replaced by wildcards. So
+[source, java]
....
call(public final void C.foo() throws ArrayOutOfBoundsException)
....
picks out call join points to that method, and the pointcut
+[source, java]
....
call(public final void *.*() throws ArrayOutOfBoundsException)
....
@@ -949,12 +816,14 @@ throw `ArrayOutOfBounds` exceptions.
The defining type name, if not present, defaults to *, so another way of
writing that pointcut would be
+[source, java]
....
call(public final void *() throws ArrayOutOfBoundsException)
....
The wildcard `..` indicates zero or more parameters, so
+[source, java]
....
execution(void m(..))
....
@@ -962,6 +831,7 @@ execution(void m(..))
picks out execution join points for void methods named `m`, of any
number of arguments, while
+[source, java]
....
execution(void m(.., int))
....
@@ -974,6 +844,7 @@ signature pattern should match methods without a particular modifier,
such as all non-public methods, the appropriate modifier should be
negated with the `!` operator. So,
+[source, java]
....
withincode(!public void foo())
....
@@ -981,6 +852,7 @@ withincode(!public void foo())
picks out all join points associated with code in null non-public void
methods named `foo`, while
+[source, java]
....
withincode(void foo())
....
@@ -991,12 +863,14 @@ named `foo`, regardless of access modifier.
Method names may contain the * wildcard, indicating any number of
characters in the method name. So
+[source, java]
....
call(int *())
....
picks out all call join points to `int` methods regardless of name, but
+[source, java]
....
call(int get*())
....
@@ -1009,6 +883,7 @@ than using a particular class name. So the execution join points of
private null constructor of a class C defined to throw an
ArithmeticException can be picked out with
+[source, java]
....
execution(private C.new() throws ArithmeticException)
....
@@ -1027,6 +902,7 @@ type used to access the method. A common mistake is to specify a
declaring type for the `call` pointcut that is a subtype of the
originally-declaring type. For example, given the class
+[source, java]
....
class Service implements Runnable {
public void run() { ... }
@@ -1035,12 +911,14 @@ class Service implements Runnable {
the following pointcut
+[source, java]
....
call(void Service.run())
....
would fail to pick out the join point for the code
+[source, java]
....
((Runnable) new Service()).run();
....
@@ -1049,6 +927,7 @@ Specifying the originally-declaring type is correct, but would pick out
any such call (here, calls to the `run()` method of any Runnable). In
this situation, consider instead picking out the target type:
+[source, java]
....
call(void run()) && target(Service)
....
@@ -1058,6 +937,7 @@ method signature specifies a declaring type, the pointcut will only
match methods declared in that type, or methods that override methods
declared in or inherited by that type. So the pointcut
+[source, java]
....
execution(public void Middle.*())
....
@@ -1068,6 +948,7 @@ Middle, even if those methods are overridden in a subclass of Middle. So
the pointcut would pick out the method-execution join point for Sub.m()
in this code:
+[source, java]
....
class Super {
protected void m() { ... }
@@ -1085,6 +966,7 @@ Type patterns may be used to pick out methods and constructors based on
their throws clauses. This allows the following two kinds of extremely
wildcarded pointcuts:
+[source, java]
....
pointcut throwsMathlike():
// each call to a method with a throws clause containing at least
@@ -1190,6 +1072,7 @@ So exact type patterns match based on usual Java scope rules.
There is a special type name, *, which is also a type pattern. * picks
out all types, including primitive types. So
+[source, java]
....
call(void foo(*))
....
@@ -1202,6 +1085,7 @@ patterns. The * wildcard matches zero or more characters characters
except for ".", so it can be used when types have a certain naming
convention. So
+[source, java]
....
handler(java.util.*Map)
....
@@ -1209,6 +1093,7 @@ handler(java.util.*Map)
picks out the types java.util.Map and java.util.java.util.HashMap, among
others, and
+[source, java]
....
handler(java.util.*)
....
@@ -1221,6 +1106,7 @@ The "`..`" wildcard matches any sequence of characters that start and
end with a ".", so it can be used to pick out all types in any
subpackage, or all inner types. So
+[source, java]
....
within(com.xerox..*)
....
@@ -1238,6 +1124,7 @@ It is possible to pick out all subtypes of a type (or a collection of
types) with the "+" wildcard. The "+" wildcard follows immediately a
type name pattern. So, while
+[source, java]
....
call(Foo.new())
....
@@ -1245,6 +1132,7 @@ call(Foo.new())
picks out all constructor call join points where an instance of exactly
type Foo is constructed,
+[source, java]
....
call(Foo+.new())
....
@@ -1252,6 +1140,7 @@ call(Foo+.new())
picks out all constructor call join points where an instance of any
subtype of Foo (including Foo itself) is constructed, and the unlikely
+[source, java]
....
call(*Handler+.new())
....
@@ -1271,6 +1160,7 @@ Type patterns are built up out of type name patterns, subtype patterns,
and array type patterns, and constructed with boolean operators `&&`,
`||`, and `!`. So
+[source, java]
....
staticinitialization(Foo || Bar)
....
@@ -1278,6 +1168,7 @@ staticinitialization(Foo || Bar)
picks out the static initializer execution join points of either Foo or
Bar, and
+[source, java]
....
call((Foo+ && ! Foo).new(..))
....
@@ -1289,6 +1180,7 @@ not Foo itself, is constructed.
Here is a summary of the pattern syntax used in AspectJ:
+[source, text]
....
MethodPattern =
[ModifiersPattern] TypePattern
@@ -1397,6 +1289,7 @@ interpretations of after advice: After the execution of a join point
completes normally, after it throws an exception, or after it does
either one. AspectJ allows after advice for any of these situations.
+[source, java]
....
aspect A {
pointcut publicCall(): call(public Object *(..));
@@ -1415,6 +1308,7 @@ aspect A {
After returning advice may not care about its returned object, in which
case it may be written
+[source, java]
....
after() returning: call(public Object *(..)) {
System.out.println("Returned normally");
@@ -1448,6 +1342,7 @@ must be declared with a return type, like a method.
Thus, a simple use of around advice is to make a particular method
constant:
+[source, java]
....
aspect A {
int around(): call(int C.foo()) {
@@ -1459,6 +1354,7 @@ aspect A {
Within the body of around advice, though, the computation of the
original join point can be executed with the special syntax
+[source, java]
....
proceed( ... )
....
@@ -1468,6 +1364,7 @@ pointcut, and returns whatever the around is declared to return. So the
following around advice will double the second argument to `foo`
whenever it is called, and then halve its result:
+[source, java]
....
aspect A {
int around(int i): call(int C.foo(Object, int)) && args(i) {
@@ -1483,6 +1380,7 @@ is originally a primitive value. And when the advice returns an Object
value, that value is converted back to whatever representation it was
originally. So another way to write the doubling and halving advice is:
+[source, java]
....
aspect A {
Object around(int i): call(int C.foo(Object, int)) && args(i) {
@@ -1500,6 +1398,7 @@ program the first call to proceed will be treated as a method call to
the `ICanProceed` instance, whereas the second call to proceed is
treated as the special proceed form.
+[source, java]
....
aspect A {
Object around(ICanProceed canProceed) : execution(* *(..)) && this(canProceed) {
@@ -1519,6 +1418,7 @@ method parameters. In particular, assigning to any parameter affects
only the value of the parameter, not the value that it came from. This
means that
+[source, java]
....
aspect A {
after() returning (int i): call(int C.foo()) {
@@ -1536,6 +1436,7 @@ less-precedent advice and the underlying join point by supplying
different values for the variables. For example, this aspect replaces
the string bound to `s` in the named pointcut `privateData`:
+[source, java]
....
aspect A {
Object around(String s): MyPointcuts.privateData(s) {
@@ -1551,6 +1452,7 @@ In the following aspect, the around advice replaces the declared target
`List` with an `ArrayList`. This is valid code at compile-time since the
types match.
+[source, java]
....
import java.util.*;
@@ -1565,6 +1467,7 @@ But imagine a simple program where the actual target is `LinkedList`. In
this case, the advice would cause a `ClassCastException` at runtime, and
`peek()` is not declared in `ArrayList`.
+[source, java]
....
public class Test {
public static void main(String[] args) {
@@ -1577,6 +1480,7 @@ The `ClassCastException` can occur even in situations where it appears
to be unnecessary, e.g., if the program is changed to call `size()`,
declared in `List`:
+[source, java]
....
public class Test {
public static void main(String[] args) {
@@ -1605,6 +1509,7 @@ signalled by the compiler.
For example, in the following declarations:
+[source, java]
....
import java.io.FileNotFoundException;
@@ -1626,22 +1531,14 @@ aspect A {
both pieces of advice are illegal. The first because the body throws an
undeclared checked exception, and the second because field get join
-points cannot throw `FileNotFoundException`s.
+points cannot throw ``FileNotFoundException``s.
The exceptions that each kind of join point in AspectJ may throw are:
method call and execution::
- the checked exceptions declared by the target method's
- +
- throws
- +
- clause.
+ the checked exceptions declared by the target method's `_throws_` clause.
constructor call and execution::
- the checked exceptions declared by the target constructor's
- +
- throws
- +
- clause.
+ the checked exceptions declared by the target constructor's `_throws_` clause.
field get and set::
no checked exceptions can be thrown from these join points.
exception handler execution::
@@ -1649,11 +1546,7 @@ exception handler execution::
static initializer execution::
no checked exceptions can be thrown from these join points.
pre-initialization and initialization::
- any exception that is in the throws clause of
- +
- all
- +
- constructors of the initialized class.
+ any exception that is in the throws clause of all constructors of the initialized class.
advice execution::
any exception that is in the throws clause of the advice.
@@ -1700,6 +1593,7 @@ precedence over the one that appears later.
These rules can lead to circularity, such as
+[source, java]
....
aspect A {
before(): execution(void main(String[] args)) {}
@@ -1747,6 +1641,7 @@ encapsulates some of the context of the advice's current or enclosing
join point. These variables exist because some pointcuts may pick out
very large collections of join points. For example, the pointcut
+[source, java]
....
pointcut publicCall(): call(public * *(..));
....
@@ -1843,6 +1738,7 @@ The effect of such a declaration is to make <OnType> support the new
method. Even if <OnType> is an interface. Even if the method is neither
public nor abstract. So the following is legal AspectJ code:
+[source, java]
....
interface Iface {}
@@ -1979,6 +1875,7 @@ Inter-type declarations raise the possibility of conflicts among locally
declared members and inter-type members. For example, assuming
`otherPackage` is not the package containing the aspect `A`, the code
+[source, java]
....
aspect A {
private Registry otherPackage.onType.r;
@@ -2001,6 +1898,7 @@ there is no conflict: The aspect cannot see such a field, and no code in
If `onType` defines a public field "`r`", there is a conflict: The
expression
+[source, java]
....
this.r = r
....
@@ -2071,6 +1969,7 @@ might define appropriate inter-type `void
fulfills the `Runnable` interface. In order to implement the methods in
the `Runnable` interface, the inter-type `run()` method must be public:
+[source, java]
....
aspect A {
declare parents: SomeClass implements Runnable;
@@ -2091,9 +1990,10 @@ initializers. The order of super-interface instantiation is observable.
We fix this order with the following properties: A supertype is
initialized before a subtype, initialized code runs only once, and the
initializers for a type's superclass are run before the initializers for
-its superinterfaces. Consider the following hierarchy where \{`Object`,
-`C`, `D`, `E`} are classes, \{`M`, `N`, `O`, `P`, `Q`} are interfaces.
+its superinterfaces. Consider the following hierarchy where {`Object`,
+`C`, `D`, `E`} are classes, {`M`, `N`, `O`, `P`, `Q`} are interfaces.
+[source, text]
....
Object M O
\ / \ /
@@ -2106,6 +2006,7 @@ its superinterfaces. Consider the following hierarchy where \{`Object`,
when a new `E` is instantiated, the initializers run in this order:
+[source, text]
....
Object M C O N D Q P E
....
@@ -2158,6 +2059,7 @@ Pointcut
For example, the aspect
+[source, java]
....
aspect A {
declare soft: Exception: execution(void main(String[] args));
@@ -2169,6 +2071,7 @@ Would, at the execution join point, catch any `Exception` and rethrow a
This is similar to what the following advice would do
+[source, java]
....
aspect A {
void around() execution(void main(String[] args)) {
@@ -2187,6 +2090,7 @@ Like advice, the declare soft form has no effect in an abstract aspect
that is not extended by a concreate aspect. So the following code will
not compile unless it is compiled with an extending concrete aspect:
+[source, java]
....
abstract aspect A {
abstract pointcut softeningPC();
@@ -2223,6 +2127,7 @@ of their name should have precedence over all other aspects, and (2) the
Logging aspect (and any aspect that extends it) should have precedence
over all non-security aspects, can be expressed by:
+[source, java]
....
declare precedence: *..*Security*, Logging+, *;
....
@@ -2235,6 +2140,7 @@ accomplished by stating that CountEntry has precedence over
DisallowNulls. This declaration could be in either aspect, or in
another, ordering aspect:
+[source, java]
....
aspect Ordering {
declare precedence: CountEntry, DisallowNulls;
@@ -2259,6 +2165,7 @@ aspect CountEntry {
It is an error for any aspect to be matched by more than one TypePattern
in a single decare precedence, so:
+[source, java]
....
declare precedence: A, B, A ; // error
....
@@ -2267,6 +2174,7 @@ However, multiple declare precedence forms may legally have this kind of
circularity. For example, each of these declare precedence is perfectly
legal:
+[source, java]
....
declare precedence: B, A;
declare precedence: A, B;
@@ -2280,6 +2188,7 @@ idiom that can be used to enforce that A and B are strongly independent.
Consider the following library aspects:
+[source, java]
....
abstract aspect Logging {
abstract pointcut logged();
@@ -2313,12 +2222,14 @@ aspects, say, MyLogging and MyProfiling. Because advice only applies
from concrete aspects, the declare precedence form only matters when
declaring precedence with concrete aspects. So
+[source, java]
....
declare precedence: Logging, Profiling;
....
has no effect, but both
+[source, java]
....
declare precedence: MyLogging, MyProfiling;
declare precedence: Logging+, Profiling+;
@@ -2526,6 +2437,7 @@ All advice runs in the context of an aspect instance, but it is possible
to write a piece of advice with a pointcut that picks out a join point
that must occur before asopect instantiation. For example:
+[source, java]
....
public class Client
{
@@ -2574,6 +2486,7 @@ private or protected resources of other types. To allow this, aspects
may be declared `privileged`. Code in priviliged aspects has access to
all members, even private ones.
+[source, java]
....
class C {
private int i = 0;
@@ -2594,6 +2507,7 @@ If a privileged aspect can access multiple versions of a particular
member, then those that it could see if it were not privileged take
precedence. For example, in the code
+[source, java]
....
class C {
private int i = 0;
diff --git a/docs/sandbox/readme-sandbox.adoc b/docs/sandbox/readme-sandbox.adoc
index 8d796128a..da4e69cbe 100644
--- a/docs/sandbox/readme-sandbox.adoc
+++ b/docs/sandbox/readme-sandbox.adoc
@@ -34,6 +34,7 @@ tells how.
extracts samples of the following form from any "source" file (currently
source, html, text, and shell scripts):
+[source, text]
....
... some text, possibly including @author tags
{comment} START-SAMPLE [anchorName] [anchor title] {end-comment}
@@ -63,6 +64,7 @@ indented only once in the source code, even though they might normally
be indented more.
** In AspectJ, indent advice pointcuts beyond the block code:
+
+[source, java]
....
before() : call(!public * com.company.library..*.*(String,..))
&& within(Runnable+) { // indent once more than code
@@ -107,6 +109,7 @@ suffixes necessary for clarity and to make sure there are unique titles
for each test. E.g., for a sample with the anchor
"`language-initialization`",
+
+[source, xml]
....
<ajc-test
dir="common"
@@ -124,6 +127,7 @@ compile.
by verifying that the error message is produced, checking either or both
of the line number and the message text. E.g.,
+
+[source, xml]
....
<compile files="declares/Declares.java, {others}"
<message kind="error" line="15" text="Factory"/>
@@ -135,6 +139,7 @@ message and the target code in sync. You can help with this by adding a
comment in the target code so people editing the code know not to fix or
move the code. E.g.,
+
+[source, java]
....
void spawn() {
new Thread(this, toString()).start(); // KEEP CE 15 declares-factory
@@ -151,6 +156,7 @@ make it easier to find the test that will break if the code is modified.
If the code is broken (e.g., if it no longer works in the latest version
of AspectJ), then prefix SAMPLE with BROKEN in the tag:
+[source, text]
....
{comment} START-BROKEN-SAMPLE ...
... sample code ...
diff --git a/docs/sandbox/trails/j2ee.adoc b/docs/sandbox/trails/j2ee.adoc
index 2697175f0..a483a7b79 100644
--- a/docs/sandbox/trails/j2ee.adoc
+++ b/docs/sandbox/trails/j2ee.adoc
@@ -37,6 +37,7 @@ up ajc as the compiler, do the following before starting Tomcat:
tell Ant to use `ajc` by setting the compiler property to the AspectJ
compiler adapter:
+
+[source, xml]
....
<servlet>
<servlet-name>jsp</servlet-name>