aclement
18 anos atrás
1 arquivos alterados com 79 adições e 77 exclusões
+ 79
- 77
docs/devGuideDB/ltw.xml
Ver arquivo
| @@ -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> | |||
Carregando…