| <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 5 Development Kit Developer's Notebook"><link rel="up" href="ltw.html" title="Chapter 12. 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 12. 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>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. </p><div class="sect2"><a name="d0e4162"></a><div class="titlepage"><div><h3 class="title"><a name="d0e4162"></a>Enabling Load-time Weaving</h3></div></div><p> AspectJ 5 supports several 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. </p><div class="variablelist"><dl><dt><a name="d0e4168"></a><span class="term">Agents</span></dt><dd><p><a name="d0e4171"></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="d0e4200"></a><span class="term">Custom Integration</span></dt><dd><p><a name="d0e4203"></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 explicity restrict by class loader which classes can be woven.</p></dd></dl></div></div><div class="sect2"><a name="d0e4206"></a><div class="titlepage"><div><h3 class="title"><a name="d0e4206"></a>Configuring Load-time Weaving with aop.xml files</h3></div></div><p>The weaver is configured using one or more <tt>META-INF/aop.xml</tt> | |
| 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: </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"> | |
| <pointcut name="tracingScope" expression="within(org.maw.*)"/> | |
| </concrete-aspect> | |
| <!-- Of the set of aspects known to the weaver, use aspects matching | |
| the type pattern "com..*" for weaving. --> | |
| <include within="com..*"/> | |
| <!-- Do not use any aspects with the @CoolAspect annotation for weaving --> | |
| <exclude within="@CoolAspect *"/> | |
| </aspects> | |
| <weaver options="-verbose -XlazyTjp"> | |
| <!-- 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.*"/> | |
| <dump within="somepack.*"/><!-- will dump weaved classes to the "./_ajdump" folder on disk (for diagnostic purpose) --> | |
| </weaver> | |
| </aspectj> | |
| </pre><p> | |
| 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. | |
| </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 "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. | |
| </p><p> | |
| <span class="emphasis"><i> | |
| Note: concrete-aspect is not available in AspectJ 1.5 M3. | |
| </i></span> | |
| </p><p> | |
| 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'. | |
| </p><p> | |
| 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. | |
| </p><p> 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 <tt>getResourceAsStream</tt> lookup) | |
| according to the following rules: </p><div class="itemizedlist"><ul><li><a name="d0e4236"></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).</li><li><a name="d0e4247"></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.</li><li><a name="d0e4249"></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.</li><li><a name="d0e4257"></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.</li></ul></div><p>It is not an error for the same aspect to be defined to the weaver in | |
| more than one visible <tt>META-INF/aop.xml</tt> 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. | |
| </p><p> A <tt>META-INF/aop.xml</tt> file will automatically be generated when | |
| using the <tt>-outjar</tt> 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. </p></div><div class="sect2"><a name="d0e4277"></a><div class="titlepage"><div><h3 class="title"><a name="d0e4277"></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="d0e4282"><a name="d0e4282"></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. If ever you need to have information | |
| when the load time weaving engine is bootstrapped (hence its logger as per <tt>-XmessageHandlerClass:...</tt> not ready yet), | |
| you can use the option <tt>-Daj.weaving.verbose=true</tt> on the JVM startup command line. Messages will then be printed | |
| on stderr as long as the message handler class is not ready. | |
| </td></tr><tr><td><tt>-1.5</tt></td><td>Run the weaver in 1.5 mode (supports autoboxing in | |
| join point matching)</td></tr><tr><td><tt>-XlazyTjp</tt></td><td>Performance optimization for aspects making use | |
| of thisJoinPoint (non-static parts)</td></tr><tr><td><tt>-Xlintfile:pathToAResource</tt></td><td>Configure lint messages as specified in the given resource (visible from this aop.xml file' classloader)</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>-proceedOnError</tt></td><td>Continue weaving even if errors occur (for example, | |
| "... already woven" errors)</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>-showWeaveInfo</tt></td><td>Issue informational messages whenever the weaver touches a class file</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 | |
| <tt>org.aspectj.bridge.IMessageHandler</tt> | |
| and that is visible from where the <tt>aop.xml</tt> 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. | |
| </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> |