| <html><head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
| <title>Configuration</title><link rel="stylesheet" href="aspectj-docs.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.44"><link rel="home" href="index.html" title="The AspectJtm Development Environment Guide"><link rel="up" href="ltw.html" title="Chapter 5. Load-Time Weaving"><link rel="previous" href="ltw-rules.html" title="Load-time Weaving Requirements"><link rel="next" href="ltw-specialcases.html" title="Special cases"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Configuration</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ltw-rules.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Load-Time Weaving</th><td width="20%" align="right"> <a accesskey="n" href="ltw-specialcases.html">Next</a></td></tr></table><hr></div><div class="sect1"><a name="ltw-configuration"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="ltw-configuration"></a>Configuration</h2></div></div><p>New in AspectJ 5 are a number of mechanisms to make load-time weaving | |
| easy to use. 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. </p><div class="sect2"><a name="enabling-load-time-weaving"></a><div class="titlepage"><div><h3 class="title"><a name="enabling-load-time-weaving"></a>Enabling Load-time Weaving</h3></div></div><p> AspectJ 5 supports several 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. </p><div class="variablelist"><dl><dt><a name="d0e2825"></a><span class="term">Agents</span></dt><dd><p><a name="d0e2828"></a>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. Configuration for the supported environments is discussed | |
| later in this chapter.</p><p> | |
| Using Java 5 JVMTI you can specify the <tt>-javaagent:pathto/aspectjweaver.jar</tt> option | |
| to the JVM.</p><p> | |
| Using BEA JRockit and Java 1.3/1.4, the very same behavior can be obtained using BEA JRockit JMAPI features with | |
| the <tt>-Xmanagement:class=org.aspectj.weaver.loadtime.JRockitAgent</tt> | |
| </p></dd><dt><a name="d0e2841"></a><span class="term">Command-line wrapper scripts <tt>aj</tt></span></dt><dd><p><a name="d0e2846"></a>The <b>aj</b> command runs Java programs in Java 1.4 or | |
| later by setting up <tt>WeavingURLClassLoader</tt> as the | |
| system class loader. | |
| For more information, see <a href="aj-ref.html#aj">aj</a>. | |
| </p><p>The <b>aj5</b> command runs Java programs in Java 5 | |
| by using the <tt>-javaagent:pathto/aspectjweaver.jar</tt> option | |
| described above. | |
| For more information, see <a href="aj-ref.html#aj">aj</a>. | |
| </p></dd><dt><a name="d0e2867"></a><span class="term">Custom class loader</span></dt><dd><p><a name="d0e2870"></a> 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 explicitly restrict by class loader which classes can be woven. | |
| For more information, see <a href="aj-ref.html#aj">aj</a> and the | |
| API documentation and source for | |
| <tt>WeavingURLClassLoader</tt> and | |
| <tt>WeavingAdapter</tt>. | |
| </p></dd></dl></div></div><div class="sect2"><a name="configuring-load-time-weaving-with-aopxml-files"></a><div class="titlepage"><div><h3 class="title"><a name="configuring-load-time-weaving-with-aopxml-files"></a>Configuring Load-time Weaving with aop xml files</h3></div></div> | |
| <p>The weaver is configured using one or more aop xml <tt>META-INF/aop.xml</tt> | |
| files located on the class loader search path. The weaver will search for either <tt>META-INF/aop.xml</tt> or | |
| <tt>META-INF/aop-ajc.xml</tt> files (the latter is produced by using the <tt>-outxml</tt> option when compiling the aspects). Each file may declare a list of | |
| 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: </p><pre class="programlisting"> | |
| <aspectj> | |
| <aspects> | |
| <!-- declare two existing aspects to the weaver --> | |
| <aspect name="com.MyAspect"/> | |
| <aspect name="com.MyAspect.Inner"/> | |
| <!-- define a concrete aspect inline --> | |
| <concrete-aspect name="com.xyz.tracing.MyTracing" | |
| extends="tracing.AbstractTracing" | |
| precedence="com.xyz.first, *"> | |
| <pointcut name="tracingScope" expression="within(org.maw.*)"/> | |
| </concrete-aspect> | |
| <!-- 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 to the weaver | |
| do not use any aspects with the @CoolAspect annotation for weaving --> | |
| <exclude within="@CoolAspect *"/> | |
| </aspects> | |
| <weaver options="-verbose"> | |
| <!-- Weave types that are within the javax.* or org.aspectj.* | |
| packages. Also weave all types in the foo package that do | |
| not have the @NoWeave annotation. --> | |
| <include within="javax.*"/> | |
| <include within="org.aspectj.*"/> | |
| <include within="(!@NoWeave foo.*) AND foo.*"/> | |
| <!-- Do not weave types within the "bar" pakage --> | |
| <exclude within="bar.*"/> | |
| <!-- Dump all types within the "com.foo.bar" package | |
| to the "./_ajdump" folder on disk (for diagnostic purposes) --> | |
| <dump within="com.foo.bar.*"/> | |
| <!-- Dump all types within the "com.foo.bar" package and sub-packages, | |
| both before are after they are woven, | |
| which can be used for byte-code generated at runtime | |
| <dump within="com.foo.bar..*" beforeandafter="true"/> | |
| </weaver> | |
| </aspectj> | |
| </pre><p> | |
| The DTD defining the format of this file is available here: | |
| http://www.eclipse.org/aspectj/dtd/aspectj.dtd. | |
| </p><p> | |
| An aop xml file contains two key sections: <tt>aspects</tt> defines one | |
| or more aspects to the weaver and controls which aspects are to be | |
| used in the weaving process; <tt>weaver</tt> defines weaver options and which | |
| types should be woven. | |
| </p><p> | |
| 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 <tt>concrete-aspect</tt> 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. | |
| Refer to the next section for more details. | |
| </p><p> | |
| The <tt>aspects</tt> element may optionally contain one or more <tt>include</tt> and | |
| <tt>exclude</tt> 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 <tt>within</tt> attribute accepts | |
| a type pattern of the same form as a within pcd, except that && | |
| and || are replaced by 'AND' and 'OR'. | |
| </p><p> | |
| Note that <tt>include</tt> and <tt>exclude</tt> 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 <tt>aspect</tt> and <tt>concrete-aspect</tt> elements | |
| must be used to declare aspects to the weaver i.e. <tt>include</tt> and <tt>exclude</tt> | |
| elements cannot be used find aspects on the class loader search path. | |
| </p><p> | |
| The <tt>weaver</tt> 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 visible to the weaver will be woven. In addition the <tt>dump</tt> | |
| element can be used capture on disk byte-code of woven classes for diagnostic purposes both before, | |
| in the case of those generated at runtime, and after the weaving process. | |
| </p><p> When several configuration files are visible from a given weaving class loader | |
| their contents are conceptually merged. | |
| The files are merged in the order they are | |
| found on the search path (with a regular <tt>getResourceAsStream</tt> lookup) | |
| according to the following rules: </p><div class="itemizedlist"><ul><li><p><a name="d0e2955"></a>The set of available aspects is the set of all | |
| declared and defined aspects (<tt>aspect</tt> and | |
| <tt>concrete-aspect</tt> elements of the <tt>aspects</tt> | |
| section).</p></li><li><p><a name="d0e2967"></a>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.</p></li><li><p><a name="d0e2970"></a> The set of types to be woven are those types matched by at | |
| least one weaver <tt>include</tt> element and not matched by any | |
| weaver <tt>exclude</tt> element. If there are no weaver include | |
| statements then all non-excluded types are included.</p></li><li><p><a name="d0e2979"></a> 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. <tt>-warn:none</tt> the most recently defined value | |
| will be used.</p></li></ul></div><p>It is not an error for the same aspect to be defined to the weaver in | |
| more than one visible aop xml file. | |
| However, if the same concrete aspect | |
| is defined in more than one 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. | |
| </p><p> A aop xml can be generated by | |
| using either the <tt>-outxml</tt> or <tt>-outxmlfile</tt> 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 <tt>-outjar</tt> option | |
| a JAR is produced that can be used | |
| with the <b>aj5</b> command or a load-time weaving environment.</p></div><div class="sect2"><a name="concrete-aspect"></a><div class="titlepage"><div><h3 class="title"><a name="concrete-aspect"></a>Using Concrete Aspects</h3></div></div><p> | |
| It is possible to make an abstract aspect concrete by means of the <tt>META-INF/aop.xml</tt> | |
| file. This is useful way to implement abstract pointcuts at deployment time, and also gives control | |
| over precedence through the <tt>precedence</tt> attribute of the | |
| <tt>concrete-aspect</tt> XML element. | |
| Consider the following: | |
| </p><pre class="programlisting"> | |
| package mypack; | |
| @Aspect | |
| public abstract class AbstractAspect { | |
| // abstract pointcut: no expression is defined | |
| @Pointcut | |
| abstract void scope(); | |
| @Before("scope() && execution(* *..doSome(..))") | |
| public void before(JoinPoint jp) { | |
| .... | |
| } | |
| } | |
| </pre><p> | |
| This aspect is equivalent to the following in code style: | |
| </p><pre class="programlisting"> | |
| package mypack; | |
| public abstract aspect AbstractAspect { | |
| // abstract pointcut: no expression is defined | |
| abstract pointcut scope(); | |
| before() : scope() && execution(* *..doSome(..)) { | |
| .... | |
| } | |
| } | |
| </pre><p> | |
| This aspect (in either style) can be made concrete using an aop xml file. | |
| It defines the abstract pointcut <tt>scope()</tt>. When using this mechanism the | |
| following rules apply: | |
| <div class="itemizedlist"><ul><li><p><a name="d0e3036"></a>The parent aspect must be abstract. It can be an @AspectJ or a | |
| regular code style aspect.</p></li><li><p><a name="d0e3039"></a>Only a simple abstract pointcut can be implemented i.e. a pointcut that doesn't expose | |
| state (through <tt>args(), this(), target(), if()</tt>). In @AspectJ syntax | |
| as illustrated in this sample, this means the method that hosts the pointcut must be abstract, | |
| have no arguments, and return void.</p></li><li><p><a name="d0e3045"></a>The concrete aspect must implement all inherited abstract pointcuts.</p></li><li><p><a name="d0e3048"></a>The concrete aspect may not implement methods so the abstract aspect it | |
| extends may not contain any abstract methods.</p></li></ul></div> | |
| </p><p> | |
| 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: | |
| </p><pre class="programlisting"> | |
| <aspectj> | |
| <aspects> | |
| <concrete-aspect name="mypack.__My__AbstractAspect" extends="mypack.AbstractAspect"> | |
| <pointcut name="scope" expression="within(yourpackage..*)"/> | |
| </concrete-aspect> | |
| <aspects> | |
| </aspectj> | |
| </pre><p> | |
| It is important to remember that the <tt>name</tt> attribute in the | |
| <tt>concrete-aspect</tt> 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 file is visible. This implies that if you need | |
| to use the <tt>aspectof</tt> methods to access the aspect instance(s) (depending on the perclause | |
| of the aspect it extends) you have to use the helper API <tt>org.aspectj.lang.Aspects.aspectOf(..)</tt> | |
| as in: | |
| </p><pre class="programlisting"> | |
| // exception handling omitted | |
| Class myConcreteAspectClass = Class.forName("mypack.__My__AbstractAspect"); | |
| // here we are using a singleton aspect | |
| AbstractAspect concreteInstance = Aspects.aspectOf(myConcreteAspectClass); | |
| </pre></div><div class="sect2"><a name="concrete-aspect-precedence"></a><div class="titlepage"><div><h3 class="title"><a name="concrete-aspect-precedence"></a>Using Concrete Aspects to define precedence</h3></div></div><p> | |
| As described in the previous section, the <tt>concrete-aspect</tt> element in | |
| <tt>META-INF/aop.xml</tt> gives the option to declare the precedence, just as | |
| <tt>@DeclarePrecedence</tt> or <tt>declare precedence</tt> do in | |
| aspect source code. | |
| </p><p> | |
| Sometimes it is necessary to declare precedence without extending any abstract aspect. | |
| It is therefore possible to use the <tt>concrete-aspect</tt> | |
| element without the <tt>extends</tt> attribute and without any | |
| <tt>pointcut</tt> nested elements, just a <tt>precedence</tt> | |
| attribute. | |
| Consider the following: | |
| </p><pre class="programlisting"> | |
| <aspectj> | |
| <aspects> | |
| <concrete-aspect name="mypack.__MyDeclarePrecedence" | |
| precedence="*..*Security*, Logging+, *"/> | |
| </aspects> | |
| </aspectj> | |
| </pre><p> | |
| This deployment time definitions is only declaring a precedence rule. You have to remember | |
| that the <tt>name</tt> 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. | |
| </p></div><div class="sect2"><a name="weaver-options"></a><div class="titlepage"><div><h3 class="title"><a name="weaver-options"></a>Weaver Options</h3></div></div><p> The table below lists the AspectJ options supported by LTW. All other options | |
| will be ignored and a warning issued. </p><div class="informaltable" id="d0e3122"><a name="d0e3122"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Option</th><th>Purpose</th></tr></thead><tbody><tr><td><tt>-verbose</tt></td><td>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 <tt>-Daj.weaving.verbose=true</tt> on the JVM startup command line. | |
| </td></tr><tr><td><tt>-debug</tt></td><td> | |
| Issue a messages for each class passed to the weaver | |
| indicating whether it was woven, excluded or ignored. | |
| Also issue messages for classes | |
| defined during the weaving process such as around advice | |
| closures and concrete aspects defined in | |
| aop xml files. | |
| </td></tr><tr><td><tt>-showWeaveInfo</tt></td><td> | |
| Issue informational messages whenever the weaver touches a class file. | |
| This option may also be enabled using the System property | |
| <tt>-Dorg.aspectj.weaver.showWeaveInfo=true</tt>. | |
| </td></tr><tr><td><tt>-Xlintfile:pathToAResource</tt></td><td>Configure lint messages as specified in the given resource (visible from the classloader for this aop xml file)</td></tr><tr><td><tt>-Xlint:default, -Xlint:ignore, ...</tt></td><td>Configure lint messages, refer to documentation for meaningfull values</td></tr><tr><td><tt>-nowarn, -warn:none</tt></td><td>Suppress warning messages</td></tr><tr><td><tt>-Xreweavable</tt></td><td>Produce class files that can subsequently be rewoven</td></tr><tr><td><tt>-XnoInline</tt></td><td>Don't inline around advice.</td></tr><tr><td><tt>-XmessageHandlerClass:...</tt></td><td>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 the | |
| <tt>org.aspectj.bridge.IMessageHandler</tt> 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. | |
| </td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ltw-rules.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="ltw-specialcases.html">Next</a></td></tr><tr><td width="40%" align="left">Load-time Weaving Requirements </td><td width="20%" align="center"><a accesskey="u" href="ltw.html">Up</a></td><td width="40%" align="right"> Special cases</td></tr></table></div></body></html> |