diff options
Diffstat (limited to 'docs/devGuideDB/ltw.xml')
| -rw-r--r-- | docs/devGuideDB/ltw.xml | 608 |
1 files changed, 0 insertions, 608 deletions
diff --git a/docs/devGuideDB/ltw.xml b/docs/devGuideDB/ltw.xml deleted file mode 100644 index 79569ad38..000000000 --- a/docs/devGuideDB/ltw.xml +++ /dev/null @@ -1,608 +0,0 @@ -<chapter id="ltw" xreflabel="Load-Time Weaving"> - <title>Load-Time Weaving</title> - - <sect1 id="ltw-introduction"> - <title>Introduction</title> - - <para> The AspectJ weaver takes class files as input and produces class files as output. - 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 - 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> - <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, - the aspects used for weaving may be in source or binary form, - and may themselves be woven by aspects.</para></listitem> - <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> - - <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> - </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 - 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. - A visible aspect is one defined by the - 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> - <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> - <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. - 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> - <para> 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. </para> - <variablelist> - <varlistentry> - <term>Agents</term> - <listitem> - <para>AspectJ 5 ships with a load-time weaving agent that - enables load-time weaving. This agent and its configuration - is 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> - Since AspectJ 1.9.7, the obsolete Oracle/BEA JRockit agent is no longer part of AspectJ. - JRockit JDK never supported Java versions higher than 1.6. Several JRockit JVM features are - now part of HotSpot and tools like Mission Control available for OpenJDK and Oracle JDK. - </para> - </listitem> - </varlistentry> - <varlistentry> - <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> - <varlistentry> - <term>Custom class loader</term> - <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 - 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> - </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> - files located on the class loader search path. 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: </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 --> - <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> -]]></programlisting> - - <para> - The DTD defining the format of this file is available here: - https://www.eclipse.org/aspectj/dtd/aspectj.dtd. - </para> - <para> - An aop.xml file contains two key sections: <literal>aspects</literal> defines one - or more aspects to the weaver and controls which aspects are to be - used in the weaving process; <literal>weaver</literal> defines weaver options and which - 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. - This is done using the <literal>concrete-aspect</literal> 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. - </para> - - <para> - 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). - 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 <literal>within</literal> attribute accepts - a type pattern of the same form as a within pcd, except that && - and || are replaced by 'AND' and 'OR'. - </para> - <para> - 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 declare 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 <literal>weaver</literal> 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 <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. - </para> - - - <para> 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 <literal>getResourceAsStream</literal> lookup) - 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. - However, if the same concrete aspect - is defined in more than one 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> 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 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: - </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> - This aspect (in either style) can be made concrete using <literal>META-INF/aop.xml</literal>. - It defines the abstract pointcut <literal>scope()</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 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 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> - </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> - 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> - <aspects> - <concrete-aspect name="mypack.__My__AbstractAspect" extends="mypack.AbstractAspect"> - <pointcut name="scope" expression="within(yourpackage..*)"/> - </concrete-aspect> - <aspects> -</aspectj> -]]></programlisting> - <para> - 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> - 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> - </sect2> - - <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> - 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 elements, just a <literal>precedence</literal> - attribute. - Consider the following: - </para> - <programlisting><![CDATA[ -<aspectj> - <aspects> - <concrete-aspect name="mypack.__MyDeclarePrecedence" - precedence="*..*Security*, Logging+, *"/> - </aspects> -</aspectj> -]]></programlisting> - <para> - 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. - </para> - </sect2> - <!-- 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 - -weaver.options=-verbose -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> - <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> - <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> - </row> - <!-- TODO option parsed but not used --> - <!-- - <row> - <entry> - <literal>-1.5</literal> - </entry> - <entry>Run the weaver in 1.5 mode (supports autoboxing in - join point matching)</entry> - </row> - --> - <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> - <!-- TODO option parsed but not used --> - <!-- - <row> - <entry> - <literal>-proceedOnError</literal> - </entry> - <entry>Continue weaving even if errors occur (for example, - "... already woven" errors)</entry> - </row> - --> - <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. - 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> - </tgroup> - </informaltable> - </sect2> - </sect1> - - <sect1 id="ltw-specialcases"> - <title>Special cases</title> - <para> - 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> - <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> - - <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> - </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> - Since AspectJ 1.9.7, the obsolete Oracle/BEA JRockit agent is no longer part of AspectJ. - JRockit JDK never supported Java versions higher than 1.6. Several JRockit JVM features are - now part of HotSpot and tools like Mission Control available for OpenJDK and Oracle JDK. - </para> - </sect2> - </sect1> -</chapter> |