123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833 |
- <chapter id="ataspectj" xreflabel="AtAspectJ">
-
- <title>An Annotation Based Development Style</title>
-
- <sect1 id="ataspectj-intro">
- <title>Introduction</title>
-
- <para>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.</para>
-
- <para>
- 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.
- </para>
-
- <para>
- 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.
- </para>
-
- </sect1>
-
- <sect1 id="ataspectj-aspects">
- <title>Aspect Declarations</title>
-
- <para>
- Aspect declarations are supported by the
- <literal>org.aspectj.lang.annotation.Aspect</literal> annotation.
- The declaration:
- </para>
-
- <programlisting><![CDATA[
- @Aspect
- public class Foo {}
- ]]></programlisting>
-
- <para>Is equivalent to:</para>
-
- <programlisting><![CDATA[
- public aspect Foo {}
- ]]></programlisting>
-
- <para>And since issingleton() is the default aspect instantiation model it is equivalent to:</para>
-
- <programlisting><![CDATA[
- @Aspect("issingleton()")
- public class Foo {}
- ]]></programlisting>
-
- <para>To specify an aspect an aspect instantiation model (the default is
- singleton), provide the perclause as the
- <literal>@Aspect</literal> value.
- For example:
- </para>
-
- <programlisting><![CDATA[
- @Aspect("perthis(execution(* abc..*(..)))")
- public class Foo {}
- ]]></programlisting>
-
- <para>is equivalent to...</para>
-
- <programlisting><![CDATA[
- public aspect Foo perthis(execution(* abc..*(..))) {}
- ]]></programlisting>
-
- <sect2>
- <title>Limitations</title>
-
- <para>Privileged aspects are not supported by the annotation style.</para>
- <!--
- <programlisting><![CDATA[
- @Aspect(isPrivileged=true)
- public class Foo {}
- ]]></programlisting>
-
- <para>is equivalent to...</para>
-
- <programlisting><![CDATA[
- public privileged aspect Foo {}
- ]]></programlisting>
- -->
- </sect2>
-
- </sect1>
-
- <sect1 id="ataspectj-pcadvice">
- <title>Pointcuts and Advice</title>
-
- <para>
- Pointcut and advice declarations can be made using the
- <literal>Pointcut, Before, After, AfterReturning, AfterThrowing,</literal>
- and
- <literal>Around</literal> annotations.
- </para>
-
- <sect2>
- <title>Pointcuts</title>
-
- <para>
- Pointcuts are specified using the
- <literal>org.aspectj.lang.annotation.Pointcut</literal> annotation
- on a method declaration. The method should have a
- <literal>void</literal>
- 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.
- </para>
-
- <para>
- As a general rule, the
- <literal>@Pointcut</literal> annotated method must have an empty method body
- and must not have any
- <literal>throws</literal> clause. If formal are bound (using
- <literal>args(), target(), this(), @args(), @target(), @this(), @annotation())</literal> in the
- pointcut, then they must appear in the method signature.
- </para>
-
- <para>
- The <literal>if()</literal> pointcut is treated specially and is discussed in a later section.
- </para>
-
- <para>Here is a simple example of a pointcut declaration in both code and @AspectJ styles:</para>
-
- <programlisting><![CDATA[
- @Pointcut("call(* *.*(..))")
- void anyCall() {}
- ]]></programlisting>
-
- <para>is equivalent to...</para>
-
- <programlisting><![CDATA[
- pointcut anyCall() : call(* *.*(..));
- ]]></programlisting>
-
-
- <para>When binding arguments, simply declare the arguments as normal in the annotated method:</para>
-
- <programlisting><![CDATA[
- @Pointcut("call(* *.*(int)) && args(i) && target(callee)")
- void someCall(int i, Foo callee) {}
- ]]></programlisting>
-
- <para>is equivalent to...</para>
-
- <programlisting><![CDATA[
- pointcut anyCall(int i, Foo callee) : call(* *.*(int)) && args(i) && target(callee);
- ]]></programlisting>
-
- <para>An example with modifiers (it is also good to remember that Java 5 annotations are not inherited):</para>
-
- <programlisting><![CDATA[
- @Pointcut("")
- protected abstract void anyCall();
- ]]></programlisting>
-
- <para>is equivalent to...</para>
-
- <programlisting><![CDATA[
- protected abstract pointcut anyCall();
- ]]></programlisting>
-
- <sect3>
- <title>Type references inside @AspectJ annotations</title>
-
- <para>
- 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
- <literal>java.lang</literal>). This
- does not apply to type patterns with wildcards, which are always resolved
- in a global scope.
- </para>
-
- <para>
- Consider the following compilation unit:
- </para>
-
- <programlisting><![CDATA[
- package org.aspectprogrammer.examples;
-
- import java.util.List;
-
- public aspect Foo {
-
- pointcut listOperation() : call(* List.*(..));
-
- pointcut anyUtilityCall() : call(* java.util..*(..));
-
- }
- ]]></programlisting>
-
- <para>
- Using the annotation style this would be written as:
- </para>
-
- <programlisting><![CDATA[
- package org.aspectprogrammer.examples;
-
- import java.util.List; // redundant but harmless
-
- @Aspect
- public class Foo {
-
- @Pointcut("call(* java.util.List.*(..))") // must qualify
- void listOperation() {}
-
- @Pointcut("call(* java.util..*(..))")
- void anyUtilityCall() {}
-
- }
- ]]></programlisting>
-
- </sect3>
-
- <sect3>
- <title>if() pointcut expressions</title>
-
- <para>In code style, it is possible to use the <literal>if(...)</literal> poincut to define
- a conditional pointcut expression which will be evaluated at runtime for each candidate join point.
- The <literal>if(...)</literal>
- body can be any valid Java boolean expression, and can use any exposed formal, as well as the join point forms
- <literal>thisJoinPoint, thisJoinPointStaticPart and thisJoinPointEnclosingStaticPart</literal>.
- </para>
-
- <para>
- 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. An <literal>if()</literal> pointcut expression can be
- declared in an <literal>@Pointcut</literal>, but must either an empty body, or be one
- of the expression <literal>if(true)</literal> or <literal>if(false)</literal>. The annotated
- method must be public, static, and return a boolean. The body of the method contains the
- condition to be evaluated. For example:
- </para>
-
- <programlisting><![CDATA[
- @Pointcut("call(* *.*(int)) && args(i) && if()")
- public static boolean someCallWithIfTest(int i) {
- return i > 0;
- }
- ]]></programlisting>
-
- <para>is equivalent to...</para>
-
- <programlisting><![CDATA[
- pointcut someCallWithIfTest(int i) : call(* *.*(int)) && args(i) && if(i > 0);
- ]]></programlisting>
-
- <para> and the following is also a valid form:</para>
-
- <programlisting><![CDATA[
- static int COUNT = 0;
-
- @Pointcut("call(* *.*(int)) && args(i) && if()")
- public static boolean someCallWithIfTest(int i, JoinPoint jp, JoinPoint.EnclosingStaticPart esjp) {
- // any legal Java expression...
- return i > 0
- && jp.getSignature().getName.startsWith("doo")
- && esjp.getSignature().getName().startsWith("test")
- && COUNT++ < 10;
- }
-
- @Before("someCallWithIfTest(anInt, jp, enc)")
- public void beforeAdviceWithRuntimeTest(int anInt, 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 ?
- }
- */
- ]]></programlisting>
-
- <para>
- It is thus possible with the annotation style to use the <literal>if()</literal> pointcut
- only within an <literal>@Pointcut</literal> expression. The <literal>if()</literal> must not contain any
- body. The annotated <literal>@Pointcut</literal> method must then be of the form <literal>public static boolean</literal>
- and can use formal bindings as usual.
- Extra <emphasis>implicit</emphasis> arguments of type JoinPoint, JoinPoint.StaticPart and JoinPoint.EnclosingStaticPart can also be used
- (this is not permitted for regular annotated pointcuts not using the <literal>if()</literal> form).
- </para>
-
- <para>
- The special forms <literal>if(true)</literal> and <literal>if(false)</literal> can be used in a more
- general way and don't imply that the pointcut method must have a body.
- You can thus write <literal>@Before("somePoincut() && if(false)")</literal>.
- </para>
-
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>Advice</title>
-
- <para>In this section we first discuss the use of annotations for
- simple advice declarations. Then we show how
- <literal>thisJoinPoint</literal>
- and its siblings are handled in the body of advice and discuss the
- treatment of
- <literal>proceed</literal> in around advice.
- </para>
-
- <para>Using the annotation style, an advice declaration is written as
- a regular Java method with one of the
- <literal>Before, After, AfterReturning,
- AfterThrowing,</literal> or
- <literal>Around</literal> annotations. Except in
- the case of around advice, the method should return void. The method should
- be declared public.
- </para>
-
- <para>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).</para>
-
- <para>The following example shows a simple before advice declaration in
- both styles:</para>
-
- <programlisting><![CDATA[
- @Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
- public void callFromFoo() {
- System.out.println("Call from Foo");
- }
- ]]></programlisting>
-
- <para>is equivalent to...</para>
-
- <programlisting><![CDATA[
- before() : call(* org.aspectprogrammer..*(..)) && this(Foo) {
- System.out.println("Call from Foo");
- }
- ]]></programlisting>
-
-
- <!--
- AMC: enhanced adviceexecution pointcuts and @AdviceName will most likely not make AJ5 1.5.0
-
- <para>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
- <literal>org.aspectj.lang.annotation.AdviceName</literal> annotation.
- The exact equivalent declarations are:
- </para>
-
- <programlisting><![CDATA[
- @AdviceName("callFromFoo")
- before() : call(* org.aspectprogrammer..*(..)) && this(Foo) {
- System.out.println("Call from Foo");
- }
-
- is equivalent to...
-
- @Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
- public void callFromFoo() {
- System.out.println("Call from Foo");
- }
- ]]></programlisting>
-
- -->
-
- <para>If the advice body needs to know which particular
- <literal>Foo</literal> instance
- is making the call, just add a parameter to the advice declaration.
- </para>
-
- <programlisting><![CDATA[
- before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
- System.out.println("Call from Foo: " + foo);
- }
- ]]></programlisting>
-
- <para>can be written as:</para>
-
- <programlisting><![CDATA[
- @Before("call(* org.aspectprogrammer..*(..)) && this(foo)")
- public void callFromFoo(Foo foo) {
- System.out.println("Call from Foo: " + foo);
- }
- ]]></programlisting>
-
- <para>If the advice body needs access to
- <literal>thisJoinPoint</literal>,
- <literal>thisJoinPointStaticPart</literal>,
- <literal>thisEnclosingJoinPointStaticPart</literal> then these need to
- be declared as additional method parameters when using the annotation
- style. <!-- TODO AV - not any more - In AspectJ 1.5.0 we require that these parameters be declared
- first in the parameter list, in later releases we may relax this
- requirement.-->
- </para>
-
- <programlisting><![CDATA[
- @Before("call(* org.aspectprogrammer..*(..)) && this(foo)")
- public void callFromFoo(JoinPoint thisJoinPoint, Foo foo) {
- System.out.println("Call from Foo: " + foo + " at "
- + thisJoinPoint);
- }
- ]]></programlisting>
-
- <para>is equivalent to...</para>
-
- <programlisting><![CDATA[
- before(Foo foo) : call(* org.aspectprogrammer..*(..)) && this(foo) {
- System.out.println("Call from Foo: " + foo + " at "
- + thisJoinPoint);
- }
- ]]></programlisting>
-
- <para>Advice that needs all three variables would be declared:</para>
-
- <programlisting><![CDATA[
- @Before("call(* org.aspectprogrammer..*(..)) && this(Foo)")
- public void callFromFoo(JoinPoint thisJoinPoint,
- JoinPoint.StaticPart thisJoinPointStaticPart,
- JoinPoint.EnclosingStaticPart thisEnclosingJoinPointStaticPart) {
- // ...
- }
- ]]></programlisting>
-
- <para>
- <literal>JoinPoint.EnclosingStaticPart</literal> is a new (empty) sub-interface
- of
- <literal>JoinPoint.StaticPart</literal> which allows the AspectJ weaver to
- distinguish based on type which of
- <literal>thisJoinPointStaticPart</literal> and
- <literal>thisEnclosingJoinPointStaticPart</literal> should be passed in a given
- parameter position.
- </para>
-
- <para>
- <literal>After</literal> advice declarations take exactly the same form
- as
- <literal>Before</literal>, as do the forms of
- <literal>AfterReturning</literal>
- and
- <literal>AfterThrowing</literal> that do not expose the return type or
- thrown exception respectively.
- </para>
-
- <para>
- 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:
- </para>
-
- <programlisting><![CDATA[
- @AfterReturning("criticalOperation()")
- public void phew() {
- System.out.println("phew");
- }
-
- @AfterReturning(pointcut="call(Foo+.new(..))",returning="f")
- public void itsAFoo(Foo f) {
- System.out.println("It's a Foo: " + f);
- }
- ]]></programlisting>
-
- <para>is equivalent to...</para>
-
- <programlisting><![CDATA[
- after() returning : criticalOperation() {
- System.out.println("phew");
- }
-
- after() returning(Foo f) : call(Foo+.new(..)) {
- System.out.println("It's a Foo: " + f);
- }
- ]]></programlisting>
-
- <para>(Note the use of the "pointcut=" prefix in front of the pointcut
- expression in the returning case).</para>
-
- <para>After throwing advice works in a similar fashion, using the
- <literal>throwing</literal> attribute when needing to expose a
- thrown exception.
- </para>
-
- <para>For around advice, we have to tackle the problem of
- <literal>proceed</literal>.
- 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
- <literal>proceed</literal> inside a method body:
- </para>
-
- <programlisting><![CDATA[
- @Around("call(* org.aspectprogrammer..*(..))")
- public Object doNothing() {
- return proceed(); // CE on this line
- }
- ]]></programlisting>
-
-
- <para>will result in a "No such method" compilation error. For this
- reason AspectJ 5 defines a new sub-interface of
- <literal>JoinPoint</literal>,
- <literal>ProceedingJoinPoint</literal>.
- </para>
-
- <programlisting><![CDATA[
- public interface ProceedingJoinPoint extends JoinPoint {
- public Object proceed(Object[] args);
- }
- ]]></programlisting>
-
- <para>The around advice given above can now be written as:</para>
-
- <programlisting><![CDATA[
- @Around("call(* org.aspectprogrammer..*(..))")
- public Object doNothing(ProceedingJoinPoint thisJoinPoint) {
- return thisJoinPoint.proceed();
- }
- ]]></programlisting>
-
- <para>Here's an example that uses parameters for the proceed call:</para>
-
- <programlisting><![CDATA[
- @Aspect
- public class ProceedAspect {
-
- @Pointcut("call(* setAge(..)) && args(i)")
- void setAge(int i) {}
-
- @Around("setAge(i)")
- public Object twiceAsOld(ProceedingJoinPoint thisJoinPoint, int i) {
- return thisJoinPoint.proceed(new Object[]{i*2}); //using Java 5 autoboxing
- }
-
- }
-
- ]]></programlisting>
-
- <para>is equivalent to:</para>
-
- <programlisting><![CDATA[
- public aspect ProceedAspect {
- pointcut setAge(int i): call(* setAge(..)) && args(i);
-
- Object around(int i): setAge(i) {
- return proceed(i*2);
- }
- }
- ]]></programlisting>
-
-
-
- <para>Note that the ProceedingJoinPoint does not need to be passed to the proceed(..) arguments.
- </para>
- </sect2>
-
- </sect1>
-
- <sect1 id="ataspectj-itds">
- <title>Inter-type Declarations</title>
-
- <para><emphasis>The features described in this section will not be supported until the
- AspectJ 5 M4 milestone build.</emphasis></para>
-
- <para>
- 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.
- </para>
-
- <para>
- Consider the following aspect:
- </para>
-
- <programlisting><![CDATA[
- public aspect MoodIndicator {
-
- public interface Moody {};
-
- private Mood Moody.mood = Mood.HAPPY;
-
- public Mood Moody.getMood() {
- return mood;
- }
-
- declare parents : org.xyz..* implements Moody;
-
- before(Moody m) : execution(* *.*(..)) && this(m) {
- System.out.println("I'm feeling " + m.getMood());
- }
- }
- ]]></programlisting>
-
- <para>
- This declares an interface
- <literal>Moody</literal>, 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
- <literal>getMoody</literal>, the type of
- <literal>this</literal>
- is
- <literal>Moody</literal> (the target type of the inter-type declaration).
- </para>
-
- <para>Using the annotation style this aspect can be written:
- </para>
-
- <programlisting><![CDATA[
- @Aspect
- public class MoodIndicator {
-
- public interface Moody {
- Mood getMood();
- };
-
- @DeclareParents("org.xzy..*")
- class MoodyImpl implements Moody {
- private Mood mood = Mood.HAPPY;
-
- public Mood getMood() {
- return mood;
- }
- }
-
- @Before("execution(* *.*(..)) && this(m)")
- void feelingMoody(Moody m) {
- System.out.println("I'm feeling " + m.getMood());
- }
- }
- ]]></programlisting>
-
- <para>
- This is very similar to the mixin mechanism supported by AspectWerkz. The
- effect of the
- <literal>@DeclareParents</literal> 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
- <literal>this</literal> has access
- to the exact same set of members as in the code style example.
- </para>
-
- <para>The annotated class may only extend
- <literal>Object</literal>, and may
- only implement a single interface. The interface implemented by the class may
- itself extend other interfaces.
- </para>
-
- </sect1>
-
- <sect1 id="ataspectj-declare">
- <title>Declare statements</title>
-
- <para>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.</para>
-
- <para>Declare precedence and declare annotation
- <emphasis>will</emphasis>
- be supported. For declare precedence, use the
- <literal>@DeclarePrecedence</literal>
- annotation as in the following example:
- </para>
-
- <programlisting><![CDATA[
- public aspect SystemArchitecture {
- declare precedence : Security*, TransactionSupport, Persistence;
-
- // ...
- }
-
- can be written as:
-
- @Aspect
- @DeclarePrecedence("Security*,org.xyz.TransactionSupport,org.xyz.Persistence")
- public class SystemArchitecture {
-
- // ...
- }
- ]]></programlisting>
-
- <para>
- Declare annotation is supported via annotations on a dummy type member. If the
- <literal>Target</literal> specification of the annotation allows it, use a field,
- otherwise declare a member of the type required by the
- <literal>Target</literal>.
- For example:
- </para>
-
- <programlisting><![CDATA[
- public aspect DeclareAnnotationExamples {
- declare annotation : org.xyz.model..* : @BusinessDomain;
-
- declare annotation : public * BankAccount+.*(..) : @Secured(role="supervisor");
-
- declare anotation : * DAO+.* : @Persisted;
-
- }
-
- can be written as...
-
- @Aspect
- public class DeclareAnnotationExamples {
-
- @DeclareAnnotation("org.xyz.model..*)
- @BusinessDomain Object modelClass;
-
- // this example assumes that the @Secured annotation has a Target
- // annotation with value ElementType.METHOD
- @DeclareAnnotation("public * org.xyz.banking.BankAccount+.*(..)")
- @Secured(role="supervisor) void bankAccountMethod();
-
- @DeclareAnnotation("* DAO+.*")
- @Persisted Object daoFields;
- }
- ]]></programlisting>
-
- <para>
- <emphasis>Note: Declare annotation is not available in AspectJ 1.5 M3 and syntax may change
- when the design and implementation is complete.</emphasis>
- </para>
-
- <para>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.</para>
-
- <para>Note that the String must be a constant and not the result of the invocation
- of a static method for example.</para>
-
- <programlisting><![CDATA[
- declare warning : call(* javax.sql..*(..)) && !within(org.xyz.daos..*)
- : "Only DAOs should be calling JDBC.";
-
- declare error : execution(* IFoo+.*(..)) && !within(org.foo..*)
- : "Only foo types can implement IFoo";
-
- can be written as...
-
- @DeclareWarning("call(* javax.sql..*(..)) && !within(org.xyz.daos..*)")
- static final String aMessage = "Only DAOs should be calling JDBC.";
-
- @DeclareError("execution(* IFoo+.*(..)) && !within(org.foo..*)")
- static final String badIFooImplementors = "Only foo types can implement IFoo";
-
- // the following is not valid since the message is not a String constant
- @DeclareError("execution(* IFoo+.*(..)) && !within(org.foo..*)")
- static final String badIFooImplementorsCorrupted = getMessage();
- static String getMessage() {
- return "Only foo types can implement IFoo " + System.currentTimeMillis();
- }
-
- ]]></programlisting>
-
-
- </sect1>
-
- <sect1 id="ataspectj-aspectof">
- <title>aspectOf() and hasAspect() methods</title>
-
- <para>A central part of AspectJ's programming model is that aspects
- written using the code style and compiled using ajc support
- <literal>aspectOf</literal> and
- <literal>hasAspect</literal> 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.
- </para>
-
- <para>To provide equivalent support for AspectJ applications compiled with
- a standard Java 5 compiler, AspectJ 5 defines the
- <literal>Aspects</literal>
- utility class:
- </para>
-
- <programlisting><![CDATA[
- public class Aspects {
-
- /* variation used for singleton, percflow, percflowbelow */
- static<T> public static T aspectOf(T aspectType) {...}
-
- /* variation used for perthis, pertarget */
- static<T> public static T aspectOf(T aspectType, Object forObject) {...}
-
- /* variation used for pertypewithin */
- static<T> 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) {...}
- }
- ]]></programlisting>
-
- <!-- TODO AV - stuff below is not done -->
- <!--
- <para>When the AspectJ weaver sees calls to these methods, it will convert
- them into the most efficient form possible (to get performance equivalent
- to a direct <literal>MyAspect.aspectOf()</literal> call).</para>
- -->
- </sect1>
- </chapter>
|