From 6c67bc69e2052ea82b1ea0e7b415ba710d1e3c19 Mon Sep 17 00:00:00 2001 From: aclement Date: Tue, 20 Dec 2005 11:54:01 +0000 Subject: [PATCH] matthews doc changes for ltw --- docs/devGuideDB/ltw.xml | 156 ++++++++++++++++++++-------------------- 1 file changed, 79 insertions(+), 77 deletions(-) diff --git a/docs/devGuideDB/ltw.xml b/docs/devGuideDB/ltw.xml index b7b6d9b73..6408d634e 100644 --- a/docs/devGuideDB/ltw.xml +++ b/docs/devGuideDB/ltw.xml @@ -33,14 +33,12 @@ 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 + As of AspectJ 5 aspects (code style or annotation style) and woven classes are + reweavable by default. If you are developing AspectJ applications that are to be used + in a load-time weaving environment with an older version of the compiler 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. - As per AspectJ 1.5.0 M3 aspects (code style or annotation style) are - reweavable by default, and weaved classes are reweavable by default as well as per AspectJ 1.5.0 M4. @@ -98,31 +96,20 @@ - Command-line wrapper script aj + Command-line wrapper scripts aj The aj command runs Java programs in Java 1.4 or later by setting up WeavingURLClassLoader as the system class loader. For more information, see . + The aj5 command runs Java programs in Java 5 + by using the -javaagent:pathto/aspectjweaver.jar option + described above. + For more information, see . + - - - - - - - - - - - - - - - - Custom class loader @@ -146,7 +133,7 @@ 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 + 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 @@ -167,11 +154,11 @@ - - @@ -184,7 +171,14 @@ - + + + + + + @@ -222,22 +216,24 @@ and || are replaced by 'AND' and 'OR'. - Note that include and exclude affects the declared list of aspects (or concrete-aspect) defined in this - sole aop.xml and has no side effect on other aop.xml files. - Also note it is required to use aspect or concrete-aspect elements and that include does not - mean "pick any aspect you 'll find" - as the aspect list must be known by the weaver. + Note that include and exclude elements affect all aspects + declared to the weaver including those in other aop.xml files. To help avoid unexpected + behaviour a lint warning is issued + if an aspect is not declared as a result of of applying these filters. + Also note aspect and concrete-aspect elements + must be used to delare aspects to the weaver i.e. include and exclude + elements cannot be used find aspects on the class loader search path. 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. + then all types visible to 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). + their contents are conceptually merged. The files are merged in the order they are found on the search path (regular getResourceAsStream lookup) according to the following rules: @@ -263,24 +259,27 @@ 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 + However, if a concrete aspect + is defined 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. + A META-INF/aop.xml can be generated by + using either the -outxml or -outxmlfile options of the AspectJ compiler. + It will simply contain a (possibly empty) set of aspect elements; one for + each abstract or concrete aspect defined. + When used in conjuction with the -outjar option + a JAR is produced that can be used + with the aj5 command or a load-time weaving environment. Using Concrete Aspects - It is possible to concretize an abstract aspect by the mean of the META-INF/aop.xml - file. This is usefull to define abstract pointcuts at deployment time, and also gives control + It is possible to make an abstract aspect concrete by means of the META-INF/aop.xml + file. This is useful way to implement abstract pointcuts at deployment time, and also gives control over precedence through the precedence attribute of the concrete-aspect XML element. Consider the following: @@ -318,24 +317,23 @@ } ]]> - This aspect (in either of its style) is a good candidate for concretization through META-INF/aop.xml. - It defines the abstract pointcut within(). It is important to remember that - concretization in this case must obey to the following rules: + This aspect (in either style) can be made concrete using META-INF/aop.xml. + It defines the abstract pointcut within(). When using this mechanism the + following rules apply: The parent aspect must be abstract. It can be an @AspectJ or a regular code style aspect. - Only simple abstract pointcut can be concretized ie pointcut that don't expose + Only a simple abstract pointcut can be implemented i.e. a pointcut that doesn't expose state (through args(), this(), target(), if()). In @AspectJ syntax - as illustrated in this sample, this means the method that hosts the pointcut is abstract, - has no arguments, and returns void. - Concretization must defines all such abstract pointcuts ie it is not possible - to have concrete-aspect inter dependancies. - Concretization can only concretize pointcuts ie there cannot be abstract method - left in the aspect. + as illustrated in this sample, this means the method that hosts the pointcut must be abstract, + have no arguments, and return void. + The concrete aspect must implement all inherited abstract pointcuts. + The concrete aspect may not implement methods so the abstract aspect it + extends may not contain any abstract methods. - If you have requirements for more complex aspect inheritance, you should consider regular aspect - inheritance instead of concretization through XML. - Given that the following XML is valid: + 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: @@ -345,10 +343,11 @@ ]]> - It is important to remember that the name attribute in the XML directive - concrete-aspect defines the fully qualified name that will be given to the - concrete aspect. It must then be a valid class name. This one will indeed be generated on the fly by the weaver internals. You must - then ensure that there won't be name collision. Also note that the concrete aspect will be + It is important to remember that the name attribute in the + concrete-aspect directive defines the fully qualified name that will be given to the + concrete aspect. It must a valid class name because the aspect will be generated on the fly by the weaver. + You must + also ensure that there are no name collisions. Note that the concrete aspect will be defined at the classloader level for which the aop.xml is visible. This implies that if you need to use the aspectof methods to access the aspect instance(s) (depending on the perclause of the aspect it extends) you have to use the helper API org.aspectj.lang.Aspects.aspectOf(..) @@ -372,10 +371,10 @@ aspect source code. - Sometimes it is required to declare precedence without extending any abstract aspect - as well. For such a need, it is possible to use the concrete-aspect + Sometimes it is necessary to declare precedence without extending any abstract aspect. + It is therefore possible to use the concrete-aspect element without the extends attribute and without any - pointcut nested element, but only with a precedence + pointcut nested elements, just a precedence attribute. Consider the following: @@ -386,7 +385,7 @@ ]]> - This deployment time declaration is only defining a precedence rule. You have to remember + This deployment time definitions is only declaring a precedence rule. You have to remember that the name attribute must be a valid fully qualified class name that will be then reserved for this concrete-aspect and must not conflict with other classes you deploy. @@ -429,12 +428,13 @@ -verbose - Issue informational messages about the weaving process. If ever you need to have information - when the load time weaving engine is bootstrapped (hence its logger as per -XmessageHandlerClass:... not ready yet), - you can use the option -Daj.weaving.verbose=true on the JVM startup command line. Messages will then be printed - on stderr as long as the message handler class is not ready. + Issue informational messages about the weaving process. Messages issued while the weaver is being + bootstrapped are accumulated until all options are parsed. If the messages are required to be output + immediately you can use the option -Daj.weaving.verbose=true on the JVM startup command line. + + -Xlintfile:pathToAResource @@ -460,6 +461,8 @@ Suppress warning messages + + -Xreweavable @@ -490,14 +494,12 @@ -XmessageHandlerClass:... Provide alternative output destination to stdout/stderr for all weaver messages. - The given value must be the full qualified class name of a class that implements - org.aspectj.bridge.IMessageHandler - and that is visible from where the aop.xml is packed. - If more than one such options are used, - the first occurence only is taken into account. - You must also be very cautious about using a custom handler since it is likely that it will be invoked - (as well as all its third parties) while the weaving is done, which means that f.e. it cannot be weaved - by the aspects that are configured within the same deployment unit. + The given value must be the full qualified class name of a class that implements the + org.aspectj.bridge.IMessageHandler interface + and is visible to the classloader with which the weaver being configured is associated. + Exercise caution when packaging a custom message handler with an application that is to + be woven. The handler (as well as classes on which it depends) cannot itself be woven + by the aspects that are declared to the same weaver. @@ -509,8 +511,8 @@ Special cases - Those classes are not exposed to the LTW infrastructure, no matter - the configuration of the aop.xml file(s): + The following classes are not exposed to the LTW infrastructure regardless of + the aop.xml file(s) used: All org.aspectj.* classes (and subpackages) - as those are needed by the infrastructure itself All java.* and javax.* classes (and subpackages) -- 2.39.5