2005-10-11 11:16:34 +02:00
|
|
|
<chapter id="ltw" xreflabel="Load-Time Weaving">
|
|
|
|
<title>Load-Time Weaving</title>
|
|
|
|
|
|
|
|
<sect1 id="ltw-introduction">
|
|
|
|
<title>Introduction</title>
|
|
|
|
|
2005-10-11 11:18:00 +02:00
|
|
|
<para> The AspectJ weaver takes class files as input and produces class files as output.
|
2005-10-11 11:16:34 +02:00
|
|
|
The weaving process itself can take place at one of three different times: compile-time,
|
|
|
|
post-compile time, and load-time. The class files produced by the weaving process (and
|
|
|
|
hence the run-time behaviour of an application) are the same regardless of the approach
|
|
|
|
chosen. </para>
|
|
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem> <para>Compile-time weaving is the simplest approach. When you have the source code
|
|
|
|
for an application, ajc will compile from source and produce woven class files as
|
|
|
|
output. The invocation of the weaver is integral to the ajc compilation process. The
|
2006-03-03 19:26:06 +01:00
|
|
|
aspects themselves may be in source or binary form.
|
|
|
|
If the aspects are required for the affected classes to compile, then
|
|
|
|
you must weave at compile-time. Aspects are required, e.g., when they
|
|
|
|
add members to a class and other classes being compiled reference the
|
|
|
|
added members.
|
|
|
|
</para></listitem>
|
2005-10-11 11:16:34 +02:00
|
|
|
<listitem> <para>Post-compile weaving (also sometimes called binary weaving) is used to weave
|
|
|
|
existing class files and JAR files. As with compile-time weaving,
|
2005-10-11 11:18:00 +02:00
|
|
|
the aspects used for weaving may be in source or binary form,
|
2006-03-03 19:26:06 +01:00
|
|
|
and may themselves be woven by aspects.</para></listitem>
|
2005-10-11 11:16:34 +02:00
|
|
|
<listitem> <para>Load-time weaving (LTW) is simply binary weaving defered until the point that
|
|
|
|
a class loader loads a class file and defines the class to the JVM. To support this,
|
|
|
|
one or more "weaving class loaders", either provided explicitly by the run-time
|
|
|
|
environment or enabled through a "weaving agent" are required. </para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
<para> You may also hear the term "run-time weaving". We define this as the weaving of
|
|
|
|
classes that have already been defined to the JVM (without reloading those
|
|
|
|
classes). AspectJ 5 does not provide explicit support for run-time weaving although
|
|
|
|
simple coding patterns can support dynamically enabling and disabling advice in aspects. </para>
|
|
|
|
|
|
|
|
<sect2 id="weaving-class-files-more-than-once" xreflabel="weaving-class-files-more-than-once">
|
|
|
|
<title>Weaving class files more than once</title>
|
|
|
|
|
2005-12-20 12:54:01 +01:00
|
|
|
<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
|
2005-10-11 11:16:34 +02:00
|
|
|
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>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="ltw-rules">
|
|
|
|
<title>Load-time Weaving Requirements</title>
|
|
|
|
|
|
|
|
<para> All load-time weaving is done in the context of a class loader, and hence the set of
|
|
|
|
aspects used for weaving and the types that can be woven are affected by the class
|
|
|
|
loader delegation model. This ensures that LTW complies with the Java 2 security model.
|
|
|
|
The following rules govern the interaction of load-time weaving with class loading: </para>
|
|
|
|
|
|
|
|
<orderedlist>
|
|
|
|
<listitem> <para>All aspects to be used for weaving must be defined to the weaver before any
|
2005-10-11 11:18:00 +02:00
|
|
|
types to be woven are loaded. This avoids types being "missed" by aspects added
|
|
|
|
later, with the result that invariants across types fail.</para></listitem>
|
|
|
|
<listitem> <para>All aspects visible to the weaver are usable.
|
2005-10-11 11:16:34 +02:00
|
|
|
A visible aspect is one defined by the
|
2005-10-11 11:18:00 +02:00
|
|
|
weaving class loader or one of its parent class loaders.
|
|
|
|
All concrete visible aspects are woven and all abstract visible aspects
|
|
|
|
may be extended.
|
|
|
|
</para></listitem>
|
2005-10-11 11:16:34 +02:00
|
|
|
<listitem><para>A class loader may only weave classes that it defines. It may not weave
|
|
|
|
classes loaded by a delegate or parent class loader.</para></listitem>
|
|
|
|
</orderedlist>
|
|
|
|
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="ltw-configuration">
|
|
|
|
<title>Configuration</title>
|
2005-10-11 11:18:00 +02:00
|
|
|
<para>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.
|
2005-10-11 11:16:34 +02:00
|
|
|
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. </para>
|
|
|
|
|
|
|
|
<sect2 id="enabling-load-time-weaving" xreflabel="enabling-load-time-weaving">
|
|
|
|
<title>Enabling Load-time Weaving</title>
|
2005-10-11 11:18:00 +02:00
|
|
|
<para> AspectJ 5 supports several ways of enabling load-time weaving for
|
2005-10-11 11:16:34 +02:00
|
|
|
an application: agents, a command-line launch script, and a set of interfaces for
|
|
|
|
integration of AspectJ load-time weaving in custom environments. </para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>Agents</term>
|
|
|
|
<listitem>
|
|
|
|
<para>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.</para>
|
|
|
|
<para>
|
|
|
|
Using Java 5 JVMTI you can specify the <literal>-javaagent:pathto/aspectjweaver.jar</literal> option
|
|
|
|
to the JVM.</para><para>
|
|
|
|
Using BEA JRockit and Java 1.3/1.4, the very same behavior can be obtained using BEA JRockit JMAPI features with
|
|
|
|
the <literal>-Xmanagement:class=org.aspectj.weaver.loadtime.JRockitAgent</literal>
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2005-10-11 11:18:00 +02:00
|
|
|
<varlistentry>
|
2005-12-20 12:54:01 +01:00
|
|
|
<term>Command-line wrapper scripts <literal>aj</literal></term>
|
2005-10-11 11:18:00 +02:00
|
|
|
<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>
|
2005-12-20 12:54:01 +01:00
|
|
|
<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>
|
2005-10-11 11:18:00 +02:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2005-10-11 11:16:34 +02:00
|
|
|
<varlistentry>
|
2005-10-11 11:18:00 +02:00
|
|
|
<term>Custom class loader</term>
|
2005-10-11 11:16:34 +02:00
|
|
|
<listitem>
|
|
|
|
<para> 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
|
2005-10-11 11:18:00 +02:00
|
|
|
user to explicitly restrict by class loader which classes can be woven.
|
|
|
|
For more information, see <xref linkend="aj"/> and the
|
|
|
|
API documentation and source for
|
|
|
|
<literal>WeavingURLClassLoader</literal> and
|
|
|
|
<literal>WeavingAdapter</literal>.
|
|
|
|
</para>
|
2005-10-11 11:16:34 +02:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</sect2>
|
|
|
|
|
|
|
|
<sect2 id="configuring-load-time-weaving-with-aopxml-files" xreflabel="configuring-load-time-weaving-with-aopxml-files">
|
|
|
|
<title>Configuring Load-time Weaving with aop.xml files</title>
|
|
|
|
|
|
|
|
<para>The weaver is configured using one or more <literal>META-INF/aop.xml</literal>
|
2006-03-27 22:18:34 +02:00
|
|
|
files located on the class loader search path. Each file may declare a list of
|
2005-12-20 12:54:01 +01:00
|
|
|
aspects to be used for weaving, type patterns describing which types
|
2005-10-11 11:16:34 +02:00
|
|
|
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: </para>
|
|
|
|
<programlisting><![CDATA[
|
|
|
|
<aspectj>
|
|
|
|
|
|
|
|
<aspects>
|
|
|
|
<!-- declare two existing aspects to the weaver -->
|
|
|
|
<aspect name="com.MyAspect"/>
|
|
|
|
<aspect name="com.MyAspect.Inner"/>
|
|
|
|
|
|
|
|
<!-- define a concrete aspect inline -->
|
2005-10-27 11:50:55 +02:00
|
|
|
<concrete-aspect name="com.xyz.tracing.MyTracing"
|
|
|
|
extends="tracing.AbstractTracing"
|
|
|
|
precedence="com.xyz.first, *">
|
2005-10-11 11:16:34 +02:00
|
|
|
<pointcut name="tracingScope" expression="within(org.maw.*)"/>
|
|
|
|
</concrete-aspect>
|
|
|
|
|
2005-12-20 12:54:01 +01:00
|
|
|
<!-- Of the set of aspects declared to the weaver
|
2005-11-07 11:04:00 +01:00
|
|
|
use aspects matching the type pattern "com..*" for weaving. -->
|
2005-10-11 11:16:34 +02:00
|
|
|
<include within="com..*"/>
|
|
|
|
|
2005-12-20 12:54:01 +01:00
|
|
|
<!-- Of the set of aspects declared to the weaver
|
2005-11-07 11:04:00 +01:00
|
|
|
do not use any aspects with the @CoolAspect annotation for weaving -->
|
2005-10-11 11:16:34 +02:00
|
|
|
<exclude within="@CoolAspect *"/>
|
|
|
|
|
|
|
|
</aspects>
|
|
|
|
|
2005-11-01 22:56:49 +01:00
|
|
|
<weaver options="-verbose">
|
2005-10-11 11:16:34 +02:00
|
|
|
<!-- 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.*"/>
|
2005-12-20 12:54:01 +01:00
|
|
|
|
|
|
|
<!-- Do not weave types within the "bar" pakage -->
|
|
|
|
<exclude within="bar.*"/>
|
|
|
|
|
2006-07-04 16:46:14 +02:00
|
|
|
<!-- Dump all types within the "com.foo.bar" package
|
2005-12-20 12:54:01 +01:00
|
|
|
to the "./_ajdump" folder on disk (for diagnostic purposes) -->
|
2006-07-04 16:46:14 +02:00
|
|
|
<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"/>
|
2005-10-11 11:16:34 +02:00
|
|
|
</weaver>
|
|
|
|
|
|
|
|
</aspectj>
|
|
|
|
|
|
|
|
]]></programlisting>
|
|
|
|
|
2008-06-13 00:15:19 +02:00
|
|
|
<para>
|
|
|
|
The DTD defining the format of this file is available here:
|
|
|
|
http://www.eclipse.org/aspectj/dtd/aspectj.dtd.
|
|
|
|
</para>
|
2005-10-11 11:16:34 +02:00
|
|
|
<para>
|
2006-07-04 16:46:14 +02:00
|
|
|
An aop.xml file contains two key sections: <literal>aspects</literal> defines one
|
2005-10-11 11:16:34 +02:00
|
|
|
or more aspects to the weaver and controls which aspects are to be
|
2006-07-04 16:46:14 +02:00
|
|
|
used in the weaving process; <literal>weaver</literal> defines weaver options and which
|
2005-10-11 11:16:34 +02:00
|
|
|
types should be woven.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
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.
|
2006-07-04 16:46:14 +02:00
|
|
|
This is done using the <literal>concrete-aspect</literal> element. A concrete-aspect
|
2005-10-11 11:16:34 +02:00
|
|
|
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.
|
2005-10-25 12:00:58 +02:00
|
|
|
Refer to the next section for more details.
|
2005-10-11 11:16:34 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2005-11-07 11:04:00 +01:00
|
|
|
The <literal>aspects</literal> element may optionally contain one or more <literal>include</literal> and
|
|
|
|
<literal>exclude</literal> elements (by default, all defined aspects are used for weaving).
|
2005-10-11 11:16:34 +02:00
|
|
|
Specifying include or exclude elements restricts the set of defined
|
|
|
|
aspects to be used for weaving to those that are matched by an include
|
2005-11-07 11:04:00 +01:00
|
|
|
pattern, but not by an exclude pattern. The <literal>within</literal> attribute accepts
|
2005-10-11 11:16:34 +02:00
|
|
|
a type pattern of the same form as a within pcd, except that &&
|
|
|
|
and || are replaced by 'AND' and 'OR'.
|
|
|
|
</para>
|
2005-11-07 11:04:00 +01:00
|
|
|
<para>
|
2005-12-20 12:54:01 +01:00
|
|
|
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
|
2006-03-27 22:18:34 +02:00
|
|
|
must be used to declare aspects to the weaver i.e. <literal>include</literal> and <literal>exclude</literal>
|
2005-12-20 12:54:01 +01:00
|
|
|
elements cannot be used find aspects on the class loader search path.
|
2005-11-07 11:04:00 +01:00
|
|
|
</para>
|
2005-10-11 11:16:34 +02:00
|
|
|
|
|
|
|
<para>
|
2006-07-04 16:46:14 +02:00
|
|
|
The <literal>weaver</literal> element is used to pass options to the weaver and to specify
|
2005-10-11 11:16:34 +02:00
|
|
|
the set of types that should be woven. If no include elements are specified
|
2006-07-04 16:46:14 +02:00
|
|
|
then all types visible to the weaver will be woven. In addition the <literal>dump</literal>
|
|
|
|
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.
|
2005-10-11 11:16:34 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
<para> When several configuration files are visible from a given weaving class loader
|
2005-12-20 12:54:01 +01:00
|
|
|
their contents are conceptually merged.
|
2005-10-11 11:16:34 +02:00
|
|
|
The files are merged in the order they are
|
2006-03-27 22:18:34 +02:00
|
|
|
found on the search path (with a regular <literal>getResourceAsStream</literal> lookup)
|
2005-10-11 11:16:34 +02:00
|
|
|
according to the following rules: </para>
|
|
|
|
<itemizedlist>
|
|
|
|
<!-- FIXME AV - looks like we can refine conf in a child CL - not good -->
|
|
|
|
<listitem> <para>The set of available aspects is the set of all
|
|
|
|
declared and defined aspects (<literal>aspect</literal> and
|
|
|
|
<literal>concrete-aspect</literal> elements of the <literal>aspects</literal>
|
|
|
|
section).</para></listitem>
|
|
|
|
<listitem> <para>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.</para></listitem>
|
|
|
|
<listitem> <para> The set of types to be woven are those types matched by at
|
|
|
|
least one weaver <literal>include</literal> element and not matched by any
|
|
|
|
weaver <literal>exclude</literal> element. If there are no weaver include
|
|
|
|
statements then all non-excluded types are included.</para></listitem>
|
|
|
|
<listitem> <para> 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. <literal>-warn:none</literal> the most recently defined value
|
|
|
|
will be used.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
|
|
|
|
<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.
|
2006-03-27 22:18:34 +02:00
|
|
|
However, if the same concrete aspect
|
|
|
|
is defined in more than one aop.xml file then an error will be issued.
|
2005-12-20 12:54:01 +01:00
|
|
|
A concrete aspect
|
2005-10-11 11:16:34 +02:00
|
|
|
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>
|
|
|
|
|
2005-12-20 12:54:01 +01:00
|
|
|
<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>
|
2005-10-11 11:16:34 +02:00
|
|
|
</sect2>
|
|
|
|
|
2005-10-25 12:00:58 +02:00
|
|
|
<sect2 id="concrete-aspect" xreflabel="concrete-aspect">
|
|
|
|
<title>Using Concrete Aspects</title>
|
|
|
|
<para>
|
2005-12-20 12:54:01 +01:00
|
|
|
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
|
2005-10-27 11:50:55 +02:00
|
|
|
over precedence through the <literal>precedence</literal> attribute of the
|
|
|
|
<literal>concrete-aspect</literal> XML element.
|
2005-10-25 12:00:58 +02:00
|
|
|
Consider the following:
|
|
|
|
</para>
|
|
|
|
<programlisting><![CDATA[
|
|
|
|
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) {
|
|
|
|
....
|
|
|
|
}
|
|
|
|
}
|
|
|
|
]]></programlisting>
|
|
|
|
<para>
|
|
|
|
This aspect is equivalent to the following in code style:
|
|
|
|
</para>
|
|
|
|
<programlisting><![CDATA[
|
|
|
|
package mypack;
|
|
|
|
|
|
|
|
public abstract aspect AbstractAspect {
|
|
|
|
|
|
|
|
// abstract pointcut: no expression is defined
|
|
|
|
abstract pointcut scope();
|
|
|
|
|
|
|
|
before() : scope() && execution(* *..doSome(..)) {
|
|
|
|
....
|
|
|
|
}
|
|
|
|
}
|
|
|
|
]]></programlisting>
|
|
|
|
<para>
|
2005-12-20 12:54:01 +01:00
|
|
|
This aspect (in either style) can be made concrete using <literal>META-INF/aop.xml</literal>.
|
2006-03-27 22:18:34 +02:00
|
|
|
It defines the abstract pointcut <literal>scope()</literal>. When using this mechanism the
|
2005-12-20 12:54:01 +01:00
|
|
|
following rules apply:
|
2005-10-25 12:00:58 +02:00
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>The parent aspect must be abstract. It can be an @AspectJ or a
|
|
|
|
regular code style aspect.</para></listitem>
|
2005-12-20 12:54:01 +01:00
|
|
|
<listitem><para>Only a simple abstract pointcut can be implemented i.e. a pointcut that doesn't expose
|
2005-10-25 12:00:58 +02:00
|
|
|
state (through <literal>args(), this(), target(), if()</literal>). In @AspectJ syntax
|
2005-12-20 12:54:01 +01:00
|
|
|
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>
|
2005-10-25 12:00:58 +02:00
|
|
|
</itemizedlist>
|
2006-03-27 22:18:34 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<emphasis>A limitation of the implementation of this feature in AspectJ 1.5.0 is that aspects defined using
|
|
|
|
aop.xml are not exposed to the weaver. This means that they are not affected by advice and ITDs defined in
|
|
|
|
other aspects. Support for this capability will be considered in a future release.</emphasis>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2005-12-20 12:54:01 +01:00
|
|
|
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:
|
2005-10-25 12:00:58 +02:00
|
|
|
</para>
|
|
|
|
<programlisting><![CDATA[
|
|
|
|
<aspectj>
|
2006-03-27 22:18:34 +02:00
|
|
|
<aspects>
|
|
|
|
<concrete-aspect name="mypack.__My__AbstractAspect" extends="mypack.AbstractAspect">
|
|
|
|
<pointcut name="scope" expression="within(yourpackage..*)"/>
|
|
|
|
</concrete-aspect>
|
|
|
|
<aspects>
|
2005-10-25 12:00:58 +02:00
|
|
|
</aspectj>
|
|
|
|
]]></programlisting>
|
|
|
|
<para>
|
2005-12-20 12:54:01 +01:00
|
|
|
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
|
2005-10-25 12:00:58 +02:00
|
|
|
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>
|
|
|
|
as in:
|
|
|
|
</para>
|
|
|
|
<programlisting><![CDATA[
|
|
|
|
// exception handling omitted
|
|
|
|
Class myConcreteAspectClass = Class.forName("mypack.__My__AbstractAspect");
|
|
|
|
|
|
|
|
// here we are using a singleton aspect
|
|
|
|
AbstractAspect concreteInstance = Aspects.aspectOf(myConcreteAspectClass);
|
|
|
|
]]></programlisting>
|
2005-10-27 13:43:16 +02:00
|
|
|
</sect2>
|
2005-10-25 12:00:58 +02:00
|
|
|
|
2005-10-27 13:43:16 +02:00
|
|
|
<sect2 id="concrete-aspect-precedence" xreflabel="concrete-aspect-precedence">
|
|
|
|
<title>Using Concrete Aspects to define precedence</title>
|
|
|
|
<para>
|
|
|
|
As described in the previous section, the <literal>concrete-aspect</literal> element in
|
|
|
|
<literal>META-INF/aop.xml</literal> gives the option to declare the precedence, just as
|
|
|
|
<literal>@DeclarePrecedence</literal> or <literal>declare precedence</literal> do in
|
|
|
|
aspect source code.
|
|
|
|
</para>
|
|
|
|
<para>
|
2005-12-20 12:54:01 +01:00
|
|
|
Sometimes it is necessary to declare precedence without extending any abstract aspect.
|
|
|
|
It is therefore possible to use the <literal>concrete-aspect</literal>
|
2005-10-27 13:43:16 +02:00
|
|
|
element without the <literal>extends</literal> attribute and without any
|
2005-12-20 12:54:01 +01:00
|
|
|
<literal>pointcut</literal> nested elements, just a <literal>precedence</literal>
|
2005-10-27 13:43:16 +02:00
|
|
|
attribute.
|
|
|
|
Consider the following:
|
|
|
|
</para>
|
|
|
|
<programlisting><![CDATA[
|
|
|
|
<aspectj>
|
2006-03-27 22:18:34 +02:00
|
|
|
<aspects>
|
|
|
|
<concrete-aspect name="mypack.__MyDeclarePrecedence"
|
|
|
|
precedence="*..*Security*, Logging+, *"/>
|
|
|
|
</aspects>
|
2005-10-27 13:43:16 +02:00
|
|
|
</aspectj>
|
|
|
|
]]></programlisting>
|
|
|
|
<para>
|
2005-12-20 12:54:01 +01:00
|
|
|
This deployment time definitions is only declaring a precedence rule. You have to remember
|
2005-10-27 13:43:16 +02:00
|
|
|
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.
|
|
|
|
</para>
|
|
|
|
</sect2>
|
2005-10-11 11:16:34 +02:00
|
|
|
<!-- TODO someone implement that -->
|
|
|
|
<!--
|
|
|
|
<sect2 id="configuring-load-time-weaving-with-properties-files" xreflabel="configuring-load-time-weaving-with-properties-files">
|
|
|
|
<title>Configuring Load-time Weaving with Properties Files</title>
|
|
|
|
<para> For memory constrained environments or those without support for XML a simple
|
|
|
|
Java Properties file can be used to configure LTW. Just like XML files,
|
|
|
|
<literal>META-INF/aop.properties</literal> files are loaded from the class loader
|
|
|
|
search path. Everything that can be configured through XML can be configured using a
|
|
|
|
Properties file, with the exception of declarative concrete aspects. For example: </para>
|
|
|
|
<programlisting><![CDATA[
|
|
|
|
aspects.names=com.MyAspect,com.MyAspect.Inner
|
|
|
|
aspects.include=com..*
|
|
|
|
aspects.exclude=@CoolAspect
|
|
|
|
|
2005-11-01 22:56:49 +01:00
|
|
|
weaver.options=-verbose
|
2005-10-11 11:16:34 +02:00
|
|
|
weaver.include=javax.* OR org.aspectj.*
|
|
|
|
]]></programlisting>
|
|
|
|
</sect2>
|
|
|
|
-->
|
|
|
|
|
|
|
|
<sect2 id="weaver-options" xreflabel="weaver-options">
|
|
|
|
<title>Weaver Options</title>
|
|
|
|
<para> The table below lists the AspectJ options supported by LTW. All other options
|
|
|
|
will be ignored and a warning issued. </para>
|
|
|
|
<informaltable>
|
|
|
|
<tgroup cols="2">
|
|
|
|
<thead>
|
|
|
|
<row>
|
|
|
|
<entry>Option</entry>
|
|
|
|
<entry>Purpose</entry>
|
|
|
|
</row>
|
|
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-verbose</literal>
|
|
|
|
</entry>
|
2005-12-20 12:54:01 +01:00
|
|
|
<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.
|
2005-10-11 11:16:34 +02:00
|
|
|
</entry>
|
2006-10-30 17:34:42 +01:00
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-debug</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>
|
|
|
|
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
|
|
|
|
<literal>META-INF/aop.xml</literal>.
|
|
|
|
</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-showWeaveInfo</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>
|
|
|
|
Issue informational messages whenever the weaver touches a class file.
|
|
|
|
This option may also be enabled using the System property
|
|
|
|
<literal>-Dorg.aspectj.weaver.showWeaveInfo=true</literal>.
|
|
|
|
</entry>
|
2005-10-11 11:16:34 +02:00
|
|
|
</row>
|
2005-12-20 12:54:01 +01:00
|
|
|
<!-- TODO option parsed but not used -->
|
|
|
|
<!--
|
2005-10-11 11:16:34 +02:00
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-1.5</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>Run the weaver in 1.5 mode (supports autoboxing in
|
|
|
|
join point matching)</entry>
|
|
|
|
</row>
|
2005-12-20 12:54:01 +01:00
|
|
|
-->
|
2005-10-11 11:16:34 +02:00
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-Xlintfile:pathToAResource</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>Configure lint messages as specified in the given resource (visible from this aop.xml file' classloader)</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-Xlint:default, -Xlint:ignore, ...</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>Configure lint messages, refer to documentation for meaningfull values</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-nowarn, -warn:none</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>Suppress warning messages</entry>
|
|
|
|
</row>
|
2005-12-20 12:54:01 +01:00
|
|
|
<!-- TODO option parsed but not used -->
|
|
|
|
<!--
|
2005-10-11 11:16:34 +02:00
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-proceedOnError</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>Continue weaving even if errors occur (for example,
|
|
|
|
"... already woven" errors)</entry>
|
|
|
|
</row>
|
2005-12-20 12:54:01 +01:00
|
|
|
-->
|
2005-10-11 11:16:34 +02:00
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-Xreweavable</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>Produce class files that can subsequently be rewoven</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-XnoInline</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>Don't inline around advice.</entry>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry>
|
|
|
|
<literal>-XmessageHandlerClass:...</literal>
|
|
|
|
</entry>
|
|
|
|
<entry>Provide alternative output destination to stdout/stderr for all weaver messages.
|
2005-12-20 12:54:01 +01:00
|
|
|
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.
|
2005-10-11 11:16:34 +02:00
|
|
|
</entry>
|
|
|
|
</row>
|
|
|
|
</tbody>
|
|
|
|
</tgroup>
|
|
|
|
</informaltable>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="ltw-specialcases">
|
|
|
|
<title>Special cases</title>
|
|
|
|
<para>
|
2005-12-20 12:54:01 +01:00
|
|
|
The following classes are not exposed to the LTW infrastructure regardless of
|
|
|
|
the <literal>aop.xml</literal> file(s) used:
|
2005-10-11 11:16:34 +02:00
|
|
|
<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>
|
|
|
|
<listitem> <para>All <literal>sun.reflect.*</literal> classes - as those are JDK specific classes used when reflective calls occurs</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Despite these restrictions, it is perfectly possible to match call join points for calls to these types providing the calling
|
|
|
|
class is exposed to the weaver. Subtypes of these excluded types that are exposed to the weaver may of course be woven.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Note that dynamic proxy representations are exposed to the LTW infrastructure and are not considered
|
|
|
|
a special case.
|
|
|
|
</para>
|
2005-11-07 11:04:00 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
Some lint options behave differently when used under load-time weaving. The <literal>adviceDidNotMatch</literal>
|
|
|
|
won't be handled as a warn (as during compile time) but as an info message.
|
|
|
|
</para>
|
2005-10-11 11:16:34 +02:00
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="ltw-packaging">
|
|
|
|
<title>Runtime Requirements for Load-time Weaving</title>
|
|
|
|
<para> To use LTW the <literal>aspectjweaver.jar</literal> library must be added to the
|
|
|
|
classpath. This contains the AspectJ 5 runtime, weaver, weaving class loader and
|
|
|
|
weaving agents. It also contains the DTD for parsing XML weaving configuration files. </para>
|
|
|
|
</sect1>
|
|
|
|
|
|
|
|
<sect1 id="ltw-agents">
|
|
|
|
<title>Supported Agents</title>
|
|
|
|
<sect2 id="jvmti" xreflabel="jvmti">
|
|
|
|
<title>JVMTI</title>
|
|
|
|
<para> When using Java 5 the JVMTI agent can be used by starting the JVM with the
|
|
|
|
following option (adapt according to the path to aspectjweaver.jar): </para>
|
|
|
|
<programlisting><![CDATA[
|
|
|
|
-javaagent:pathto/aspectjweaver.jar
|
|
|
|
]]></programlisting>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="jrockit" xreflabel="jrockit">
|
|
|
|
<title>JRockit with Java 1.3/1.4 (use JVMTI on Java 5)</title>
|
|
|
|
<para> The JRockit agent is configured with the following JVM option: </para>
|
|
|
|
<programlisting><![CDATA[
|
|
|
|
-Xmanagement:class=org.aspectj.weaver.loadtime.JRockitAgent
|
|
|
|
]]></programlisting>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|