From 0c8315087053985cae6defeaa2e3f9377968de88 Mon Sep 17 00:00:00 2001 From: acolyer Date: Wed, 19 Jan 2005 09:35:55 +0000 Subject: [PATCH] updates for ltw and annotations --- docs/adk15ProgGuideDB/adk15notebook.xml | 9 +- docs/adk15ProgGuideDB/ataspectj.xml | 655 ++++++++++++++++++++++++ docs/adk15ProgGuideDB/ltw.xml | 361 +++++++++++++ 3 files changed, 1023 insertions(+), 2 deletions(-) create mode 100644 docs/adk15ProgGuideDB/ataspectj.xml create mode 100644 docs/adk15ProgGuideDB/ltw.xml diff --git a/docs/adk15ProgGuideDB/adk15notebook.xml b/docs/adk15ProgGuideDB/adk15notebook.xml index d3f71630c..61252e628 100644 --- a/docs/adk15ProgGuideDB/adk15notebook.xml +++ b/docs/adk15ProgGuideDB/adk15notebook.xml @@ -11,6 +11,8 @@ + + ]> @@ -35,8 +37,9 @@ This guide describes the changes to the AspectJ language - and tools in AspectJ 5. These changes are primarily, but not exclusively, - to support Java 5 (Tiger) features. + and tools in AspectJ 5. These include support for Java 5 (Tiger) features, + enhancements to load-time weaving, an support for an annotation-based + development style for aspects. If you are new to AspectJ, we recommend you start by reading the programming guide. @@ -62,8 +65,10 @@ &varargs; &enumeratedtypes; &pertypewithin; + &ataspectj; &reflection; &miscellaneous; + <w; &grammar; diff --git a/docs/adk15ProgGuideDB/ataspectj.xml b/docs/adk15ProgGuideDB/ataspectj.xml new file mode 100644 index 000000000..080199054 --- /dev/null +++ b/docs/adk15ProgGuideDB/ataspectj.xml @@ -0,0 +1,655 @@ + + + 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. + + + + 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: + + + + + Is equivalent to: + + + + Privileged aspects are declared as: + + + + To specify an aspect an aspect instantiation model (the default is + singleton), use the instantionModel and + perClausePattern attributes. For example: + + + + The full definitions of the Aspect annotation type and the + AspectInstantiationModel enumerated type are: + + + + + + + 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: + + + + An example with modifiers: + + + + + 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 + to not apply to type patterns with wildcards, which are always resolved + in a global scope. + + + + Consider the following compilation unit: + + + + + + Using the annotation style this would be written as: + + + + + 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 + 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 + 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 + 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 + both styles: + + + + 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: + + + + 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 + be declared as additional method parameters when using the annotation + style. 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. + + + + 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 + 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. + + + 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 need for the "value=" 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. + 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: + + + + + 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: + + + + Here's an example that uses parameters for the proceed call: + + + + + + + + + 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 + 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: + + + + + + This is very similar to the mixin mechanism supported by AspectWerkz. The + 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 + 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 + 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 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. + For example: + + + + + 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. + + + + + + + + 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 + utility class: + + + public static T aspectOf(T aspectType) {...} + + /* variation used for perthis, pertarget */ + static public static T aspectOf(T aspectType, Object forObject) {...} + + /* variation used for pertypewithin */ + 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) {...} + } + ]]> + + 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 MyAspect.aspectOf() call). + + + diff --git a/docs/adk15ProgGuideDB/ltw.xml b/docs/adk15ProgGuideDB/ltw.xml new file mode 100644 index 000000000..1f0bb9d8a --- /dev/null +++ b/docs/adk15ProgGuideDB/ltw.xml @@ -0,0 +1,361 @@ + + Load-Time Weaving + + + Introduction + + The AspectJ 5 weaver takes class files as input and produces class files as output. + The weaving process itself can take place at one of three different times: compile-time, + post-compile time, and load-time. The class files produced by the weaving process (and + hence the run-time behaviour of an application) are the same regardless of the approach + chosen. + + + Compile-time weaving is the simplest approach. When you have the source code + for an application, ajc will compile from source and produce woven class files as + output. The invocation of the weaver is integral to the ajc compilation process. The + aspects themselves may be in source or binary form. + Post-compile weaving (also sometimes called binary weaving) is used to weave + existing class files and JAR files. As with compile-time weaving, + the aspects used for weaving may be in source or binary form. + Load-time weaving (LTW) is simply binary weaving defered until the point that + a class loader loads a class file and defines the class to the JVM. To support this, + one or more "weaving class loaders", either provided explicitly by the run-time + environment or enabled through a "weaving agent" are required. + + + You may also hear the term "run-time weaving". We define this as the weaving of + classes that have already been defined to the JVM (without reloading those + classes). AspectJ 5 does not provide explicit support for run-time weaving although + simple coding patterns can support dynamically enabling and disabling advice in aspects. + + + Weaving class files more than once + + By default a class file that has been woven by the AspectJ compiler cannot + subsequently be rewoven (passed as input to the weaver). If you are developing + AspectJ applications that are to be used in a load-time weaving environment, you + need to specify the -Xreweavable compiler option when building + them. This causes AspectJ to save additional state in the class files that is used + to support subsequent reweaving. + + + + + Load-time Weaving Requirements + + All load-time weaving is done in the context of a class loader, and hence the set of + aspects used for weaving and the types that can be woven are affected by the class + loader delegation model. This ensures that LTW complies with the Java 2 security model. + The following rules govern the interaction of load-time weaving with class loading: + + + All aspects to be used for weaving must be defined to the weaver before any + types to be woven are loaded. + All abstract and concrete aspects visible to the weaver + are available for extending (abstract aspects) and using for weaving. + A visible aspect is one defined by the + weaving class loader or one of its parent class loaders. + A class loader may only weave classes that it defines. It may not weave + classes loaded by a delegate or parent class loader. + + + + + + Configuration + AspectJ 5 supports a number of mechanisms designed to make load-time weaving as + easy to use as possibe. The load-time weaving mechanism is chosen through JVM startup options. + Configuration files determine the set of aspects to be used for weaving and which + types will be woven. Additional diagnostic options allow the user to debug the configuration and + weaving process. + + + Enabling Load-time Weaving + AspectJ 5 supports three different ways of enabling load-time weaving for + an application: agents, a command-line launch script, and a set of interfaces for + integration of AspectJ load-time weaving in custom environments. + + + Agents + + 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. + Using Java 5 for example, you can specify the "-javaagent" option + to the JVM. Configuration for the supported environments is discussed + later in this chapter. AspectJ 5 + has several agents including those that use JVMTI, and the + JRockit MAPI. + + + + Command line + + AspectJ includes a script "aj" that allows programs executed at + the command line to take advantage of load-time weaving. + The script is customized when AspectJ is installed depending on the chosen + JDK. For example, for JDK 1.4 the script uses the + -Djava.system.class.loader system property to replace + the system class loader with a weaving class loader allowing classes + loaded from the CLASSPATH to be woven. + For JDK 1.5 the JVMTI weaving agent is used allowing classes loaded by all + class loaders to be woven. Versions of the JDK prior to 1.3 are not + supported by the "aj" mechanism. + + + + Custom Integration + + A public interface is provided to allow a user written class loader + to instantiate a weaver and weave classes after loading and before + defining them in the JVM. This enables load-time weaving to be supported in + environments where no weaving agent is available. It also allows the + user to explicity restrict by class loader which classes can be woven. + + + + + + + Configuring Load-time Weaving with aop.xml files + + The weaver is configured using one or more META-INF/aop.xml + files located on the class loader search path. Each file may define a list of + concrete aspects to be used for weaving, type patterns describing which types + should woven, and a set of options to be passed to the weaver. In addition AspectJ 5 + supports the definition of concrete aspects in XML. 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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + An aop.xml file contains two key sections: "aspects" defines one + or more aspects to the weaver and controls which aspects are to be + used in the weaving process; "weaver" defines weaver options and which + types should be woven. + + + + The simplest way to define an aspect to the weaver is to + specify the fully-qualified name of the aspect type in an aspect element. + You can also + declare (and define to the weaver) aspects inline in the aop.xml file. + This is done using the "concrete-aspect" element. A concrete-aspect + declaration must provide a pointcut definition for every abstract + pointcut in the abstract aspect it extends. This mechanism is a + useful way of externalizing configuration for infrastructure and + auxiliary aspects where the pointcut definitions themselves can be + considered part of the configuration of the service. + + + + The aspects element may optionally contain one or more include and + exclude elements (by default, all defined aspects are used for weaving). + Specifying include or exclude elements restricts the set of defined + aspects to be used for weaving to those that are matched by an include + pattern, but not by an exclude pattern. The 'within' attribute accepts + a type pattern of the same form as a within pcd, except that && + and || are replaced by 'AND' and 'OR'. + + + + The weaver element is used to pass options to the weaver and to specify + the set of types that should be woven. If no include elements are specified + then all types seen by the weaver will be woven. + + + + When several configuration files are visible from a given weaving class loader + their contents are conceptually merged (this applies to both aop.xml files + and to aop.properties files as described in the next section). + The files are merged in the order they are + found on the search path (regular getResourceAsStream lookup) + according to the following rules: + + The set of available aspects is the set of all + declared and defined aspects (aspect and + concrete-aspect elements of the aspects + section). + The set of aspects used for weaving is the subset of the available + aspects that are matched by at least one include statement and are not matched + by any exclude statements. If there are no include statements then all non-excluded + aspects are included. + The set of types to be woven are those types matched by at + least one weaver include element and not matched by any + weaver exclude element. If there are no weaver include + statements then all non-excluded types are included. + The weaver options are derived by taking the union of the + options specified in each of the weaver options attribute specifications. Where an + option takes a value e.g. -warn:none the most recently defined value + will be used. + + + It is not an error for the same aspect to be defined to the weaver in + more than one visible META-INF/aop.xml file. + However, if a declarative concrete aspect + is declared in more than aop.xml file then an error will be issued. + A concrete aspect + defined in this way will be used to weave types loaded by the + class loader that loaded the aop.xml file in which it was defined. + + + A META-INF/aop.xml file will automatically be generated when + using the -outjar option of the AspectJ compiler. + It will simply contain a (possibly empty) set of aspect elements, one for + each concrete aspect included in the JAR. + + + + Configuring Load-time Weaving with Properties Files + For memory constrained environments or those without support for XML a simple + Java Properties file can be used to configure LTW. Just like XML files, + META-INF/aop.properties files are loaded from the class loader + search path. Everything that can be configured through XML can be configured using a + Properties file, with the exception of declarative concrete aspects. For example: + + + + + Weaver Options + The table below lists the AspectJ options supported by LTW. All other options + will be ignored and a warning issued. + + + + + Option + Purpose + + + + + + -1.5 + + Run the weaver in 1.5 mode (supports autoboxing in + join point matching) + + + + -XlazyTjp + + Performance optimization for aspects making use + of thisJoinPoint (non-static parts) + + + + -nowarn, -warn:none + + Suppress warning messages + + + + -proceedOnError + + Continue weaving even if errors occur (for example, + "... already woven" errors) + + + + -verbose + + Issue informational messages about the weaving process + + + + -Xreweavable + + Produce class files that can subsequently be rewoven + + + + -Xnoinline + + Don't inline around advice. + + + + -showWeaveInfo + + Issue informational messages whenever the weaver touches a class file + + + + -XmessageHolderClass + + Provide alternative output destination to stderr for all weaver messages + + + + + + + + + Runtime Requirements for Load-time Weaving + To use LTW the aspectjweaver.jar library must be added to the + classpath. This contains the AspectJ 5 runtime, weaver, weaving class loader and + weaving agents. It also contains the DTD for parsing XML weaving configuration files. + + + + Supported Agents + + JVMTI + When using JDK 1.5 the JVMTI agent can be used by starting the JVM with the + following option: + + + + JRockit + The JRockit agent is configured with the following JVM option: + + + + -- 2.39.5