diff options
Diffstat (limited to 'docs/devGuideDB')
| -rw-r--r-- | docs/devGuideDB/ltw.xml | 156 |
1 files 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 @@ <sect2 id="weaving-class-files-more-than-once" xreflabel="weaving-class-files-more-than-once"> <title>Weaving class files more than once</title> - <para> 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 + <para> 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 <literal>-Xreweavable</literal> compiler option when building them. This causes AspectJ to save additional state in the class files that is used to support subsequent reweaving. </para> - <para>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.</para> </sect2> </sect1> @@ -98,31 +96,20 @@ </listitem> </varlistentry> <varlistentry> - <term>Command-line wrapper script <literal>aj</literal></term> + <term>Command-line wrapper scripts <literal>aj</literal></term> <listitem> <para>The <command>aj</command> command runs Java programs in Java 1.4 or later by setting up <literal>WeavingURLClassLoader</literal> as the system class loader. For more information, see <xref linkend="aj"/>. </para> + <para>The <command>aj5</command> command runs Java programs in Java 5 + by using the <literal>-javaagent:pathto/aspectjweaver.jar</literal> option + described above. + For more information, see <xref linkend="aj"/>. + </para> </listitem> </varlistentry> - <!-- FIXME: must be made consistent (aop.xml , CL hierarchy etc) --> -<!-- <varlistentry>--> -<!-- <term>Command line</term>--> -<!-- <listitem>--> -<!-- <para> 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--> -<!-- <literal>-Djava.system.class.loader</literal> 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. </para>--> -<!-- </listitem>--> -<!-- </varlistentry>--> <varlistentry> <term>Custom class loader</term> <listitem> @@ -146,7 +133,7 @@ <para>The weaver is configured using one or more <literal>META-INF/aop.xml</literal> 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 @@ <pointcut name="tracingScope" expression="within(org.maw.*)"/> </concrete-aspect> - <!-- Of the set of aspects declared in this sole aop.xml, + <!-- Of the set of aspects declared to the weaver use aspects matching the type pattern "com..*" for weaving. --> <include within="com..*"/> - <!-- Of the set of aspects declared in this sole aop.xml, + <!-- Of the set of aspects declared to the weaver do not use any aspects with the @CoolAspect annotation for weaving --> <exclude within="@CoolAspect *"/> @@ -184,7 +171,14 @@ <include within="javax.*"/> <include within="org.aspectj.*"/> <include within="(!@NoWeave foo.*) AND foo.*"/> - <dump within="somepack.*"/><!-- will dump weaved classes to the "./_ajdump" folder on disk (for diagnostic purpose) --> + + <!-- Do not weave types within the "bar" pakage --> + <exclude within="bar.*"/> + + <!-- Dump all types within the "somepack" package, + both before are after they are woven, + to the "./_ajdump" folder on disk (for diagnostic purposes) --> + <dump within="somepack.*" /> </weaver> </aspectj> @@ -222,22 +216,24 @@ and || are replaced by 'AND' and 'OR'. </para> <para> - Note that <literal>include</literal> and <literal>exclude</literal> 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 <literal>aspect</literal> or <literal>concrete-aspect</literal> 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 <literal>include</literal> and <literal>exclude</literal> 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 <literal>aspect</literal> and <literal>concrete-aspect</literal> elements + must be used to delare aspects to the weaver i.e. <literal>include</literal> and <literal>exclude</literal> + elements cannot be used find aspects on the class loader search path. </para> <para> 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. </para> <para> 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 <literal>getResourceAsStream</literal> lookup) according to the following rules: </para> @@ -263,24 +259,27 @@ <para>It is not an error for the same aspect to be defined to the weaver in more than one visible <literal>META-INF/aop.xml</literal> 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. </para> - <para> A <literal>META-INF/aop.xml</literal> file will automatically be generated when - using the <literal>-outjar</literal> 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. </para> + <para> A <literal>META-INF/aop.xml</literal> can be generated by + using either the <literal>-outxml</literal> or <literal>-outxmlfile</literal> 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 <literal>-outjar</literal> option + a JAR is produced that can be used + with the <command>aj5</command> command or a load-time weaving environment.</para> </sect2> <sect2 id="concrete-aspect" xreflabel="concrete-aspect"> <title>Using Concrete Aspects</title> <para> - It is possible to concretize an abstract aspect by the mean of the <literal>META-INF/aop.xml</literal> - 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 <literal>META-INF/aop.xml</literal> + file. This is useful way to implement abstract pointcuts at deployment time, and also gives control over precedence through the <literal>precedence</literal> attribute of the <literal>concrete-aspect</literal> XML element. Consider the following: @@ -318,24 +317,23 @@ } ]]></programlisting> <para> - This aspect (in either of its style) is a good candidate for concretization through <literal>META-INF/aop.xml</literal>. - It defines the abstract pointcut <literal>within()</literal>. 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 <literal>META-INF/aop.xml</literal>. + It defines the abstract pointcut <literal>within()</literal>. When using this mechanism the + following rules apply: <itemizedlist> <listitem><para>The parent aspect must be abstract. It can be an @AspectJ or a regular code style aspect.</para></listitem> - <listitem><para>Only simple abstract pointcut can be concretized ie pointcut that don't expose + <listitem><para>Only a simple abstract pointcut can be implemented i.e. a pointcut that doesn't expose state (through <literal>args(), this(), target(), if()</literal>). In @AspectJ syntax - as illustrated in this sample, this means the method that hosts the pointcut is abstract, - has no arguments, and returns void.</para></listitem> - <listitem><para>Concretization must defines all such abstract pointcuts ie it is not possible - to have <literal>concrete-aspect</literal> inter dependancies.</para></listitem> - <listitem><para>Concretization can only concretize pointcuts ie there cannot be abstract method - left in the aspect.</para></listitem> + as illustrated in this sample, this means the method that hosts the pointcut must be abstract, + have no arguments, and return void.</para></listitem> + <listitem><para>The concrete aspect must implement all inherited abstract pointcuts.</para></listitem> + <listitem><para>The concrete aspect may not implement methods so the abstract aspect it + extends may not contain any abstract methods.</para></listitem> </itemizedlist> - 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: </para> <programlisting><![CDATA[ <aspectj> @@ -345,10 +343,11 @@ </aspectj> ]]></programlisting> <para> - It is important to remember that the <literal>name</literal> attribute in the XML directive - <literal>concrete-aspect</literal> 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 <literal>name</literal> attribute in the + <literal>concrete-aspect</literal> 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 <literal>aspectof</literal> methods to access the aspect instance(s) (depending on the perclause of the aspect it extends) you have to use the helper API <literal>org.aspectj.lang.Aspects.aspectOf(..)</literal> @@ -372,10 +371,10 @@ aspect source code. </para> <para> - Sometimes it is required to declare precedence without extending any abstract aspect - as well. For such a need, it is possible to use the <literal>concrete-aspect</literal> + Sometimes it is necessary to declare precedence without extending any abstract aspect. + It is therefore possible to use the <literal>concrete-aspect</literal> element without the <literal>extends</literal> attribute and without any - <literal>pointcut</literal> nested element, but only with a <literal>precedence</literal> + <literal>pointcut</literal> nested elements, just a <literal>precedence</literal> attribute. Consider the following: </para> @@ -386,7 +385,7 @@ </aspectj> ]]></programlisting> <para> - 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 <literal>name</literal> 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 @@ <entry> <literal>-verbose</literal> </entry> - <entry>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 <literal>-XmessageHandlerClass:...</literal> not ready yet), - you can use the option <literal>-Daj.weaving.verbose=true</literal> on the JVM startup command line. Messages will then be printed - on stderr as long as the message handler class is not ready. + <entry>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 <literal>-Daj.weaving.verbose=true</literal> on the JVM startup command line. </entry> </row> + <!-- TODO option parsed but not used --> + <!-- <row> <entry> <literal>-1.5</literal> @@ -442,6 +442,7 @@ <entry>Run the weaver in 1.5 mode (supports autoboxing in join point matching)</entry> </row> + --> <row> <entry> <literal>-Xlintfile:pathToAResource</literal> @@ -460,6 +461,8 @@ </entry> <entry>Suppress warning messages</entry> </row> + <!-- TODO option parsed but not used --> + <!-- <row> <entry> <literal>-proceedOnError</literal> @@ -467,6 +470,7 @@ <entry>Continue weaving even if errors occur (for example, "... already woven" errors)</entry> </row> + --> <row> <entry> <literal>-Xreweavable</literal> @@ -490,14 +494,12 @@ <literal>-XmessageHandlerClass:...</literal> </entry> <entry>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 - <literal>org.aspectj.bridge.IMessageHandler</literal> - and that is visible from where the <literal>aop.xml</literal> 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 + <literal>org.aspectj.bridge.IMessageHandler</literal> 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. </entry> </row> </tbody> @@ -509,8 +511,8 @@ <sect1 id="ltw-specialcases"> <title>Special cases</title> <para> - Those classes are not exposed to the LTW infrastructure, no matter - the configuration of the <literal>aop.xml</literal> file(s): + The following classes are not exposed to the LTW infrastructure regardless of + the <literal>aop.xml</literal> file(s) used: <itemizedlist> <listitem> <para>All <literal>org.aspectj.*</literal> classes (and subpackages) - as those are needed by the infrastructure itself</para></listitem> <listitem> <para>All <literal>java.*</literal> and <literal>javax.*</literal> classes (and subpackages)</para></listitem> |