From f9bd27ed34fccf28f1c21aa31b5b05fc4e58d86c Mon Sep 17 00:00:00 2001 From: avasseur Date: Thu, 9 Jun 2005 13:44:48 +0000 Subject: [PATCH] @style if doc --- docs/adk15ProgGuideDB/ataspectj.xml | 837 ++++++++++++++++------------ 1 file changed, 494 insertions(+), 343 deletions(-) diff --git a/docs/adk15ProgGuideDB/ataspectj.xml b/docs/adk15ProgGuideDB/ataspectj.xml index 6274c10de..37e48de06 100644 --- a/docs/adk15ProgGuideDB/ataspectj.xml +++ b/docs/adk15ProgGuideDB/ataspectj.xml @@ -1,376 +1,512 @@ - An Annotation Based Development Style - - - Introduction - - In addition to the familiar AspectJ code-based style of aspect + An Annotation Based Development Style + + + Introduction + + In addition to the familiar AspectJ code-based style of aspect declaration, AspectJ 5 also supports an annotation-based style of aspect declaration. We informally call the set of annotations that support this development style the "@AspectJ" annotations. - - + + AspectJ 5 allows aspects and their members to be specified using either the code style or the annotation style. Whichever style you use, the AspectJ weaver ensures that your program has exactly the same semantics. It is, to quote a famous advertising campaign, "a choice, not a compromise". The two styles can be mixed within a single application, and even within a single source file, though - we doubt this latter mix will be recommended in practice. - - - + we doubt this latter mix will be recommended in practice. + + + The use of the @AspectJ annotations means that there are large classes of AspectJ applications that can be compiled by a regular Java 5 compiler, and subsequently woven by the AspectJ weaver (for example, as an additional build stage, or as late as class load-time). In this chapter we introduce the @AspectJ annotations and show how they can be used to declare aspects and aspect members. - - - - - - Aspect Declarations - - - Aspect declarations are supported by the - org.aspectj.lang.annotation.Aspect annotation. - The declaration: - - - + + + + + Aspect Declarations + + + Aspect declarations are supported by the + org.aspectj.lang.annotation.Aspect annotation. + The declaration: + + + - - Is equivalent to: + ]]> + + Is equivalent to: - + ]]> - 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. - For example: - - And since issingleton() is the default aspect instantiation model it is equivalent to: + + + + + 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. + For example: + + + - - - - - Pointcuts and Advice - - - Pointcut and advice declarations can be made using the - Pointcut, Before, After, AfterReturning, AfterThrowing, - and Around annotations. - - - - Pointcuts - - - Pointcuts are specified using the - org.aspectj.lang.annotation.Pointcut annotation - on a method declaration. The method should have a void + ]]> + + + + + Pointcuts and Advice + + + Pointcut and advice declarations can be made using the + Pointcut, Before, After, AfterReturning, AfterThrowing, + and + Around annotations. + + + + Pointcuts + + + Pointcuts are specified using the + org.aspectj.lang.annotation.Pointcut annotation + on a method declaration. The method should have a + void return type. The parameters of the method correspond to the parameters of the pointcut. The modifiers of the method correspond to the modifiers - of the pointcut. The method body should be empty and there should be no - throws clause. - - - A simple example: - - + + + As a general rule, the + @Pointcut annotated method must have an empty method body + and must not have any + throws clause. If formal are bound (using + args(), target(), this(), @args(), @target(), @this(), @annotation()) in the + pointcut, then they must appear in the method signature. + + + + There is one special case to the general rule for when you use + if() pointcut + as detailled in the next section. + + + A simple example: + + - - An example with modifiers: - - + + + An example with formal bindings: + + + + + + + An example with modifiers (it is also good to remember that Java 5 annotations are not inherited): + + - - + ]]> + + Using the code style, types referenced in pointcut expressions are resolved with respect to the imported types in the compilation unit. When using the annotation style, types referenced in pointcut expressions are resolved in the absence of any imports and so have to be fully qualified if they are not by default visible to the - declaring type (outside of the declaring package and java.lang). This + declaring type (outside of the declaring package and + java.lang). This to not apply to type patterns with wildcards, which are always resolved - in a global scope. - - - + in a global scope. + + + Consider the following compilation unit: - - - + + - - - Using the annotation style this would be written as: - - - + + + Using the annotation style this would be written as: + + + + + 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. + + 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(...) + 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. + + + + 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: + + + 0; + } + + is equivalent to... + + pointcut someCallWithIfTest(int i) : call(* *.*(int)) && args(i) && if(i > 0); + ]]> + + and the following is also a valid form: + + 0 + && jp.getSignature().getName.startsWith("doo") + && esjp.getSignature().getName().startsWith("test") + && COUNT++ < 10; } - ]]> - - The value attribute of the - Pointcut declaration may contain any valid - AspectJ pointcut declaration. - - - - - Advice - - In this section we first discuss the use of annotations for - simple advice declarations. Then we show how thisJoinPoint + + @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) { + //... + } + + // Note that the following is NOT valid + /* + @Before("call(* *.*(int)) && args(i) && if()") + public void advice(int i) { + // so you were writing an advice or an if body ? + } + */ + ]]> + + + 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 + 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). + + + + The special forms if(true) and if(false) can be used in a more + general way and don't imply that the pointcut method must have a body. + You can thus write @Before("somePoincut() && if(false)"). + + + + + + Advice + + In this section we first discuss the use of annotations for + simple advice declarations. Then we show how + thisJoinPoint and its siblings are handled in the body of advice and discuss the - treatment of proceed in around advice. - - Using the annotation style, an advice declaration is written as - a regular Java method with one of the Before, After, AfterReturning, - AfterThrowing, or Around annotations. Except in + treatment of + proceed in around advice. + + + Using the annotation style, an advice declaration is written as + a regular Java method with one of the + Before, After, AfterReturning, + AfterThrowing, or + Around annotations. Except in the case of around advice, the method should return void. The method should - be declared public. - - A method that has an advice annotation is treated exactly as an + be declared public. + + + 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). - - The following example shows a simple before advice declaration in + + The following example shows a simple before advice declaration in both styles: - - - Notice one slight difference between the two advice declarations: in + ]]> + + Notice one slight difference between the two advice declarations: in the annotation style, the advice has a name, "callFromFoo". Even though advice cannot be invoked explicitly, this name is useful in join point matching when advising advice execution. For this reason, and to preserve exact semantic equivalence between the two styles, we also support the - org.aspectj.lang.annotation.AdviceName annotation. - The exact equivalent declarations are: + org.aspectj.lang.annotation.AdviceName annotation. + The exact equivalent declarations are: + - - - If the advice body needs to know which particular Foo - was doing the calling, just add a parameter to the advice declaration. + ]]> + + If the advice body needs to know which particular + Foo + was doing the calling, just add a parameter to the advice declaration. + - - - If the advice body needs access to thisJoinPoint, - thisJoinPointStaticPart, - thisEnclosingJoinPointStaticPart then these need to + ]]> + + If the advice body needs access to + thisJoinPoint, + thisJoinPointStaticPart, + thisEnclosingJoinPointStaticPart then these need to be declared as additional method parameters when using the annotation style. + first in the parameter list, in later releases we may relax this + requirement.--> + - - - Advice that needs all three variables would be declared: + ]]> + + Advice that needs all three variables would be declared: - - - - JoinPoint.EnclosingStaticPart is a new (empty) sub-interface - of JoinPoint.StaticPart which allows the AspectJ weaver to - distinguish based on type which of thisJoinPointStaticPart and - thisEnclosingJoinPointStaticPart should be passed in a given + ]]> + + + JoinPoint.EnclosingStaticPart is a new (empty) sub-interface + of + JoinPoint.StaticPart which allows the AspectJ weaver to + distinguish based on type which of + thisJoinPointStaticPart and + thisEnclosingJoinPointStaticPart should be passed in a given parameter position. - - - After advice declarations take exactly the same form - as Before, as do the forms of AfterReturning - and AfterThrowing that do not expose the return type or - thrown exception respectively. - - + + + + After advice declarations take exactly the same form + as + Before, as do the forms of + AfterReturning + and + AfterThrowing that do not expose the return type or + thrown exception respectively. + + + 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: - - - + + - - (Note the use of the "pointcut=" prefix in front of the pointcut + } + ]]> + + (Note the use of the "pointcut=" prefix in front of the pointcut expression in the returning case). - - After throwing advice works in a similar fashion, using the - throwing attribute when needing to expose a - thrown exception. - - For around advice, we have to tackle the problem of proceed. + + After throwing advice works in a similar fashion, using the + throwing attribute when needing to expose a + thrown exception. + + + For around advice, we have to tackle the problem of + proceed. One of 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: + A straight call to + proceed inside a method body: + - - - - will result in a "No such method" compilation error. For this - reason AspectJ 5 defines a new sub-interface of JoinPoint, - ProceedingJoinPoint. - - + + + will result in a "No such method" compilation error. For this + reason AspectJ 5 defines a new sub-interface of + JoinPoint, + ProceedingJoinPoint. + + + - - The around advice given above can now be written as: + ]]> - The around advice given above can now be written as: + + - - Here's an example that uses parameters for the proceed call: + ]]> + + Here's an example that uses parameters for the proceed call: - - - - - - - - Inter-type Declarations - - + ]]> + + + + + + + Inter-type Declarations + + 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 and the annotation style. We also want to support compilation of a large set of AspectJ applications using a standard Java 5 compiler. For these reasons, in the initial release of AspectJ 5 we will only support inter-type declarations on interfaces using the annotation style. - - - + + + Consider the following aspect: - - - + + - - - This declares an interface Moody, and then makes two + ]]> + + + This declares an interface + Moody, and then makes two inter-type declarations on the interface - a field that is private to the aspect, and a method that returns the mood. Within the body of the inter-type - declared method getMoody, the type of this - is Moody (the target type of the inter-type declaration). - - - Using the annotation style this aspect can be written: - - - getMoody, the type of + this + is + Moody (the target type of the inter-type declaration). + + + Using the annotation style this aspect can be written: + + + - - + ]]> + + This is very similar to the mixin mechanism supported by AspectWerkz. The - effect of the @DeclareParents annotation is equivalent to + effect of the + @DeclareParents annotation is equivalent to a declare parents statement that all types matching the type pattern implement the interface implemented by the annotated class. In addition, the member declarations within the annotated class are treated as inter-type declarations on the implemented interface. Note how this scheme operates within the constraints - of Java type checking and ensures that this has access - to the exact same set of members as in the code style example. - - The annotated class may only extend Object, and may + of Java type checking and ensures that + this has access + to the exact same set of members as in the code style example. + + + The annotated class may only extend + Object, and may only implement a single interface. The interface implemented by the class may itself extend other interfaces. - - - - - - Declare statements - - The previous section on inter-type declarations covered the case + + + + + + Declare statements + + The previous section on inter-type declarations covered the case of declare parents ... implements. The 1.5.0 release of AspectJ 5 will not support annotation style declarations for declare parents ... extends and declare soft (programs with these declarations would not in general be compilable by a regular Java 5 compiler, reducing the priority of their implementation). These may be supported in a future release. - - Declare precedence and declare annotation will - be supported. For declare precedence, use the @DeclarePrecedence - annotation as in the following example: - Declare precedence and declare annotation + will + be supported. For declare precedence, use the + @DeclarePrecedence + annotation as in the following example: + + + - - + ]]> + + Declare annotation is supported via annotations on a dummy type member. If the - Target specification of the annotation allows it, use a field, - otherwise declare a member of the type required by the Target. + Target specification of the annotation allows it, use a field, + otherwise declare a member of the type required by the + Target. For example: - - - + + - - We also support annotation style declarations for declare warning and + @Persisted Object daoFields; + } + ]]> + + We also support annotation style declarations for declare warning and declare error - any corresponding warnings and errors will be emitted at weave time, not when the aspects containing the declarations are compiled. (This is the same behaviour as when using declare warning or error with the code style). Declare warning and error declarations are made by annotating a string constant whose value is the message to be issued. - Note that the String must be a constant and not the result of the invocation + Note that the String must be a constant and not the result of the invocation of a static method for example. - - - - - - - aspectOf() and hasAspect() methods - - A central part of AspectJ's programming model is that aspects - written using the code style and compiled using ajc support - aspectOf and hasAspect static + ]]> + + + + + + aspectOf() and hasAspect() methods + + A central part of AspectJ's programming model is that aspects + written using the code style and compiled using ajc support + aspectOf and + hasAspect static methods. When developing an aspect using the annotation style and compiling using a regular Java 5 compiler, these methods will not be visible to the compiler and will result in a 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 + 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: - - - + + public static T aspectOf(T aspectType) {...} + static public static T aspectOf(T aspectType) {...} /* variation used for perthis, pertarget */ - static public static T aspectOf(T aspectType, Object forObject) {...} + static public static T aspectOf(T aspectType, Object forObject) {...} /* variation used for pertypewithin */ - static public static T aspectOf(T aspectType, Class forType) {...} - + static public static T aspectOf(T aspectType, Class forType) {...} + /* variation used for singleton, percflow, percflowbelow */ public static boolean hasAspect(Object anAspect) {...} - + /* variation used for perthis, pertarget */ public static boolean hasAspect(Object anAspect, Object forObject) {...} - + /* variation used for pertypewithin */ public static boolean hasAspect(Object anAspect, Class forType) {...} } - ]]> - - - - + ]]> + + + + -- 2.39.5