From c9cacff1d61d108c2e3ddf3b4b81a17cd26a1b9c Mon Sep 17 00:00:00 2001 From: acolyer Date: Thu, 25 Aug 2005 12:49:31 +0000 Subject: updates for M3, mostly tidying and making it clear what is and is not supported in the M3 build --- docs/adk15ProgGuideDB/ataspectj.xml | 202 +++++++++++++++++++++--------------- docs/adk15ProgGuideDB/generics.xml | 4 +- docs/adk15ProgGuideDB/ltw.xml | 18 ++-- 3 files changed, 131 insertions(+), 93 deletions(-) (limited to 'docs') diff --git a/docs/adk15ProgGuideDB/ataspectj.xml b/docs/adk15ProgGuideDB/ataspectj.xml index 717d5edb9..720d21b61 100644 --- a/docs/adk15ProgGuideDB/ataspectj.xml +++ b/docs/adk15ProgGuideDB/ataspectj.xml @@ -58,18 +58,6 @@ public class Foo {} ]]> - - Privileged aspects are not supported by the annotation style - To specify an aspect an aspect instantiation model (the default is singleton), provide the perclause as the @Aspect value. @@ -79,12 +67,32 @@ - is equivalent to... + is equivalent to... + + + Limitations + + Privileged aspects are not supported by the annotation style. + + + @@ -120,48 +128,52 @@ - There is one special case to the general rule for when you use - if() pointcut - as detailled in the next section. + The if() pointcut is treated specially and is discussed in a later section. - A simple example: + Here is a simple example of a pointcut declaration in both code and @AspectJ styles: - is equivalent to... + is equivalent to... + - An example with formal bindings: + When binding arguments, simply declare the arguments as normal in the annotated method: - is equivalent to... + is equivalent to... + - - - An example with modifiers (it is also good to remember that Java 5 annotations are not inherited): - is equivalent to... + is equivalent to... + + + Type references inside @AspectJ annotations + Using the code style, types referenced in pointcut expressions are resolved with respect to the imported types in the compilation unit. @@ -170,7 +182,7 @@ to be fully qualified if they are not by default visible to the declaring type (outside of the declaring package and java.lang). This - to not apply to type patterns with wildcards, which are always resolved + does not apply to type patterns with wildcards, which are always resolved in a global scope. @@ -213,16 +225,14 @@ } ]]> - The - value attribute of the - Pointcut declaration may contain any valid - AspectJ pointcut declaration - though if() pointcut is a special case explained below. - + - The special case for the if() pointcut. + + if() pointcut expressions - In code style, it is possible to use the if(...) poincut to implement - conditional pointcut whose residual if form will be evaluated at runtime. The if(...) + In code style, it is possible to use the if(...) poincut to define + a conditional pointcut expression which will be evaluated at runtime for each candidate join point. + The if(...) body can be any valid Java boolean expression, and can use any exposed formal, as well as the join point forms thisJoinPoint, thisJoinPointStaticPart and thisJoinPointEnclosingStaticPart. @@ -230,7 +240,11 @@ When using the annotation style, it would be really a pain to write a valid Java expression within the annotation value so the syntax differs sligthly, whilst providing the very same - semantics and runtime behaviour. Take the following examples: + semantics and runtime behaviour. An if() pointcut expression can be + declared in an @Pointcut, but must either an empty body, or be one + of the expression if(true) or if(false). The annotated + method must be public, static, and return a boolean. The body of the method contains the + condition to be evaluated. For example: 0; } + ]]> - is equivalent to... + is equivalent to... + 0); ]]> @@ -251,15 +267,15 @@ @Pointcut("call(* *.*(int)) && args(i) && if()") public static boolean someCallWithIfTest(int i, JoinPoint jp, JoinPoint.EnclosingStaticPart esjp) { - // can call any kind of method (though this method is a static one) + // any legal Java expression... return i > 0 && jp.getSignature().getName.startsWith("doo") && esjp.getSignature().getName().startsWith("test") && COUNT++ < 10; } - @Before("someCallWithIfTest(arg0, jp, enc)") // see how the pointcut is referenced: we obey its exact signature - public void beforeAdviceWithRuntimeTest(int arg0, JoinPoint jp, JoinPoint.EnclosingStaticPart enc) { + @Before("someCallWithIfTest(anInt, jp, enc)") + public void beforeAdviceWithRuntimeTest(int anInt, JoinPoint jp, JoinPoint.EnclosingStaticPart enc) { //... } @@ -275,10 +291,10 @@ It is thus possible with the annotation style to use the if() pointcut only within an @Pointcut expression. The if() must not contain any - body. The so annotated @Pointcut method must then be of the form public static boolean + body. The annotated @Pointcut method must then be of the form public static boolean and can use formal bindings as usual. - Extra implicit (thus unbound) arguments of type JoinPoint, JoinPoint.StaticPart and JoinPoint.EnclosingStaticPart can also be used - (they can't for regular pointcut without if() form). + Extra implicit arguments of type JoinPoint, JoinPoint.StaticPart and JoinPoint.EnclosingStaticPart can also be used + (this is not permitted for regular annotated pointcuts not using the if() form). @@ -287,6 +303,8 @@ You can thus write @Before("somePoincut() && if(false)"). + + @@ -312,27 +330,31 @@ A method that has an advice annotation is treated exactly as an advice declaration by AspectJ's weaver. This includes the join points that arise when the advice is executed (an adviceexecution join point, not a - method execution join point), and the restriction that advice cannot be - invoked explicitly (the weaver will issue an error if an advice method - is explicitly invoked). + method execution join point). The following example shows a simple before advice declaration in both styles: - - is equivalent to... + is equivalent to... - @Before("call(* org.aspectprogrammer..*(..)) && this(Foo)") - public void callFromFoo() { + + ]]> + - Notice one slight difference between the two advice declarations: in + If the advice body needs to know which particular - Foo - was doing the calling, just add a parameter to the advice declaration. + Foo instance + is making the call, just add a parameter to the advice declaration. - is equivalent to... + can be written as: + + + is equivalent to... + + Advice that needs all three variables would be declared: - can be written as... + is equivalent to... - @AfterReturning("criticalOperation()") - public void phew() { + @@ -507,16 +535,6 @@ Here's an example that uses parameters for the proceed call: + is equivalent to: + + + + + +Note that the ProceedingJoinPoint does not need to be passed to the proceed(..) arguments. + @@ -540,6 +573,9 @@ Inter-type Declarations + The features described in this section will not be supported until the + AspectJ 5 M4 milestone build. + Inter-type declarations are challenging to support using an annotation style. It's very important to preserve the exact same semantics between the code style @@ -703,8 +739,8 @@ ]]> - Note: Declare annotation is not available in AspectJ 1.5 M3 and syntax might change - when it will be available. + Note: Declare annotation is not available in AspectJ 1.5 M3 and syntax may change + when the design and implementation is complete. We also support annotation style declarations for declare warning and diff --git a/docs/adk15ProgGuideDB/generics.xml b/docs/adk15ProgGuideDB/generics.xml index 1514d7ded..089e07cab 100644 --- a/docs/adk15ProgGuideDB/generics.xml +++ b/docs/adk15ProgGuideDB/generics.xml @@ -1100,14 +1100,14 @@ public abstract aspect ParentChildRelationship { /** generic interface implemented by parents */ - interface ParentHasChildren{ + interface ParentHasChildren{ List getChildren(); void addChild(C child); void removeChild(C child); } /** generic interface implemented by children */ - interface ChildHasParent

{ + interface ChildHasParent

{ P getParent(); void setParent(P parent); } diff --git a/docs/adk15ProgGuideDB/ltw.xml b/docs/adk15ProgGuideDB/ltw.xml index 5fcc30777..6297959a4 100644 --- a/docs/adk15ProgGuideDB/ltw.xml +++ b/docs/adk15ProgGuideDB/ltw.xml @@ -84,11 +84,12 @@ AspectJ 5 ships with a number of load-time weaving agents that enable load-time weaving. These agents and their configuration are execution environment dependent. Configuration for the supported environments is discussed - later in this chapter.
- Using Java 5 JVMTI you can specify the -javaagent:pathto/aspectjweaver.jar option - to the JVM.
+ later in this chapter. + + Using Java 5 JVMTI you can specify the -javaagent:pathto/aspectjweaver.jar option + to the JVM. Using BEA JRockit and Java 1.3/1.4, the very same behavior can be obtained using BEA JRockit JMAPI features with - the -Xmanagement:class=org.aspectj.weaver.loadtime.JRockitAgent + the -Xmanagement:class=org.aspectj.weaver.loadtime.JRockitAgent @@ -189,7 +190,9 @@ + Note: concrete-aspect is not available in AspectJ 1.5 M3. + @@ -383,12 +386,11 @@ - Despite those special cases, it is perfectly possible to have call pointcut on those classes members providing the callee - class is not itself a speciall case, as well as execution pointcut on subclasses of those providing subclasses are not themselves - a special case. + Despite these restrictions, it is perfectly possible to match call join points for calls to these types providing the calling + class is exposed to the weaver. Subtypes of these excluded types that are exposed to the weaver may of course be woven. - It is also worth understanding that dynamic proxy representations are exposed to the LTW infrastructure and are not considered + Note that dynamic proxy representations are exposed to the LTW infrastructure and are not considered a special case. -- cgit v1.2.3