| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>The AspectJtm Problem Diagnosis Guide</title><link rel="stylesheet" href="aspectj-docs.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.44"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" id="d0e1"><div class="titlepage"><div><h1 class="title"><a name="d0e1"></a>The AspectJ<sup>tm</sup> Problem Diagnosis Guide</h1></div><div><h3 class="author">the AspectJ Team</h3></div><div><div class="legalnotice"><p>Copyright (c) 2006 IBM Corporation and others. |
| 2006 Contributors. |
| All rights reserved. |
| </p></div></div><div><div class="abstract"><p><a name="d0e15"></a><b>Abstract</b></p><p> |
| This guide describes how to configure the AspectJ compiler/weaver to provide |
| information for diagnosing problems in the input programs, the |
| compiler/weaver or its configuration. |
| </p><p> |
| The AspectJ compiler and weaver can provide lots of information for diagnosing |
| problems in building AspectJ programs. For problems in the input program, |
| there are a number of default warning and error messages, as well as many |
| configurable "lint" messages, all of which can be emitted normally, |
| logged using standard facilities, or intercepted programmatically. |
| These are discussed in <a href="#messages">Messages</a>. Since most errors |
| relate to writing pointcuts incorrectly, there is a section on |
| <a href="#pointcuts">Debugging Pointcuts</a>. |
| </p><p> |
| For problems with the compiler/weaver itself there are three facilities |
| that enable the AspectJ developers to resolve bugs even when it is |
| too hard to deliver a reproducible test case: |
| <div class="orderedlist"><ol type="1"><li><p><a name="d0e27"></a><a href="#trace">Tracing</a> can be enabled to track progress up to the time of a failure;</p></li><li><p><a name="d0e31"></a><a href="#ajcore">AspectJ Core Files</a> can give a relatively complete picture of the state of |
| the world at the time of a failure; and </p></li><li><p><a name="d0e35"></a><a href="#ltwdump">Dumping classes during load-time weaving</a> is a way to capture both |
| input and output classes during load-time weaving. |
| </p></li></ol></div> |
| </p><p> |
| This guide describes how to configure messages to get the right information |
| and how to configure traces, dumps, and core files. Although the compiler/weaver |
| operates in roughly three modes (from the command-line, embedded in an IDE, |
| and enabled as load-time weaving), the principles are basically the same for |
| all modes. The differences lie in how to set up diagnostics and what |
| information is likely to be relevant. |
| </p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt>1. <a href="#messages">Messages</a></dt><dd><dl><dt><a href="#messages-introduction">Introduction</a></dt><dd><dl><dt><a href="#messages-introduction-config">Configuring Messages</a></dt></dl></dd><dt><a href="#messages-scenarios">Message scenarios</a></dt><dd><dl><dt><a href="#messages-scenarios-ct">Compile-time weaving scenarios</a></dt><dt><a href="#messages-scenarios-ltw">Load-time weaving scenarios</a></dt></dl></dd><dt><a href="#messages-xlint">Lint messages</a></dt></dl></dd><dt>2. <a href="#pointcuts">Debugging Pointcuts</a></dt><dd><dl><dt><a href="#pointcuts-introduction">Introduction</a></dt><dt><a href="#pointcuts-debugging">Debugging pointcuts</a></dt></dl></dd><dt>3. <a href="#ajcore">AspectJ Core Files</a></dt><dd><dl><dt><a href="#ajcore-introduction">Introduction</a></dt><dd><dl><dt><a href="#configuration">Configuring dump files</a></dt><dt><a href="#ajcore-examples">AJCore File Examples</a></dt></dl></dd></dl></dd><dt>4. <a href="#trace">Tracing</a></dt><dd><dl><dt><a href="#trace-introduction">Introduction</a></dt><dd><dl><dt><a href="#trace-configuration">Configuring Tracing</a></dt><dt><a href="#trace-examples">Examples</a></dt></dl></dd></dl></dd><dt>5. <a href="#ltwdump">Dumping classes during load-time weaving</a></dt><dd><dl><dt><a href="#ltwdump-introduction">Introduction</a></dt><dd><dl><dt><a href="#ltw-examples">Configuring bytecode dumping in load-time weaving</a></dt><dt><a href="#ltwdump-examples">LTW Dump Examples</a></dt></dl></dd></dl></dd></dl></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="messages"></a>Chapter 1. Messages</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#messages-introduction">Introduction</a></dt><dd><dl><dt><a href="#messages-introduction-config">Configuring Messages</a></dt></dl></dd><dt><a href="#messages-scenarios">Message scenarios</a></dt><dd><dl><dt><a href="#messages-scenarios-ct">Compile-time weaving scenarios</a></dt><dt><a href="#messages-scenarios-ltw">Load-time weaving scenarios</a></dt></dl></dd><dt><a href="#messages-xlint">Lint messages</a></dt></dl></div><div class="sect1"><a name="messages-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="messages-introduction"></a>Introduction</h2></div></div><p> |
| Messages point out potential problems in the input program; some |
| are clearly problems (errors), but many more may depend on what |
| the programmer intends. To keep the noise down the latter are treated |
| as warnings which can be ignored by the programmer or information |
| which are hidden. However, when investigating |
| unexpected behavior it's helpful to show them. This section describes how |
| to configure messages, presents some problem scenarios when |
| compiling or doing load-time weaving, and summarizes some of the |
| more relevant messages. |
| </p><div class="sect2"><a name="messages-introduction-config"></a><div class="titlepage"><div><h3 class="title"><a name="messages-introduction-config"></a>Configuring Messages</h3></div></div><p> |
| The compiler offers <tt>-verbose</tt>, |
| <tt>-warning</tt>, and <tt>-XLint</tt> options |
| when invoked using the command-line, Ant, or embedded in an IDE. |
| All options are listed in the AspectJ Development Environment Guide |
| sections for |
| <a href="../devguide/ajc-ref.html" target="_top">Ajc</a> and |
| <a href="../devguide/antTasks-iajc.html" target="_top">Ant Tasks</a>. |
| The <a href="../devguide/ltw.html" target="_top">Load-time Weaving</a> |
| section describes how to use XML configuration files and |
| system properties to pass options to the weaver. (You can also |
| pass options to the weaver using system properties in build- |
| time weaving.) |
| The <tt>-verbose</tt> option has the effect of including |
| messages level "info", which are normally ignored. |
| Both <tt>warning</tt> and <tt>XLint</tt> |
| enable you to identify specific messages to emit, but warning |
| messages tend to be the same provided by the underlying Eclipse |
| JDT (Java) compiler, while XLint messages are emitted by the |
| AspectJ compiler or weaver. Obviously, during load-time weaving |
| only weaver messages will be emitted. Similarly, if aspects |
| are compiled but not woven, then only compiler messages will be |
| emitted. However, the usual case for the compiler/weaver working |
| at build time is to emit both compiler and weaver messages. |
| </p><p> The tables below list some options, System Properties (for LTW only) and Java 5 annotations |
| used to control AspectJ messages. The method |
| of configuration depends on your environment so please refer to the relevant |
| documentation for |
| <a href="../devguide/ajc-ref.html" target="_top">ajc</a>, |
| <a href="../devguide/antTasks.html" target="_top">Ant</a> or |
| <a href="../devguide/ltw-configuration.html#weaver-options" target="_top">LTW</a>. |
| </p><p> |
| <div class="informaltable" id="d0e95"><a name="d0e95"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody><tr><td><tt>-verbose</tt></td><td> |
| Show informational messages including AspectJ version |
| and build date. |
| </td></tr><tr><td><tt>-debug</tt></td><td> |
| (Load-time weaving only). Show debugging messages such as |
| which classes are being woven or those that are excluded. |
| (This is not related to the compiler -g option to |
| include debug information in the output .class files.) |
| </td></tr><tr><td><tt>-showWeaveInfo</tt></td><td> |
| Show weaving messages. |
| </td></tr><tr><td><tt>-Xlint</tt></td><td> |
| Control level of lint messages. |
| </td></tr><tr><td><tt>messageHolderClass</tt>/ |
| <tt>-XmessageHolderClass:</tt></td><td> |
| In Ant tasks and LTW respectively specify the class to receive all messages. |
| See |
| <a href="../devguide/antTasks-iajc.html#antTasks-iajc-options" target="_top"> |
| iajc task options</a> or |
| <a href="../devguide/ltw-configuration.html#weaver-options" target="_top"> |
| Weaver Options</a>. |
| </td></tr></tbody></table></div> |
| </p><p> |
| <div class="informaltable" id="d0e147"><a name="d0e147"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>System Property</th><th>Description</th></tr></thead><tbody><tr><td><tt>aj.weaving.verbose</tt></td><td> |
| Show informational messages including AspectJ version and build date |
| (same as <tt>-verbose</tt> option). |
| </td></tr><tr><td><tt>org.aspectj.weaver.showWeaveInfo</tt></td><td> |
| Show weaving messages |
| (same as <tt>-showWeaveInfo</tt> option). |
| </td></tr><tr><td><tt>org.aspectj.weaving.messages</tt></td><td> |
| Set this system property to enable tracing of all compiler |
| messages. See <a href="#trace-configuration">Configuring Tracing</a>. |
| </td></tr></tbody></table></div> |
| </p><p> |
| <div class="informaltable" id="d0e185"><a name="d0e185"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Annotation</th><th>Description</th></tr></thead><tbody><tr><td><tt>@SuppressAjWarnings</tt></td><td> |
| Include this is Java 5 code to suppress AspectJ |
| warnings associated with the next line of code. |
| </td></tr></tbody></table></div> |
| </p></div></div><div class="sect1"><a name="messages-scenarios"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="messages-scenarios"></a>Message scenarios</h2></div></div><div class="sect2"><a name="messages-scenarios-ct"></a><div class="titlepage"><div><h3 class="title"><a name="messages-scenarios-ct"></a>Compile-time weaving scenarios</h3></div></div><div class="sect3"><a name="messages-scenarios-ct-adviceNotWoven"></a><div class="titlepage"><div><h4 class="title"><a name="messages-scenarios-ct-adviceNotWoven"></a>Advice not woven</h4></div></div><p>This means that the pointcut for the advice did not match, |
| and it should be debugged as described in |
| <a href="#pointcuts">Debugging Pointcuts</a>.</p></div></div><div class="sect2"><a name="messages-scenarios-ltw"></a><div class="titlepage"><div><h3 class="title"><a name="messages-scenarios-ltw"></a>Load-time weaving scenarios</h3></div></div><p> You can use <tt>META-INF/aop.xml</tt> to control which |
| messages are produced during LTW. The following example will produce |
| basic informational messages about the lifecyle of the weaver in |
| addition to any warning or error messages. </p><pre class="programlisting"> |
| <aspectj> |
| <weaver options="-verbose"> |
| </weaver> |
| </aspectj> |
| </pre><p>The messages indicate which <tt>META-INF/aop.xml</tt> |
| configurations file(s) are being used. Each message is also preceeded by the |
| name of the defining class loader associated with weaver. You can use this |
| information in a large system to distinguish between different applications each |
| of which will typically have its own class loader. </p><pre class="programlisting"> |
| [AppClassLoader@92e78c] info AspectJ Weaver Version 1.5.3 built on Thursday Oct 26, 2006 at 17:22:31 GMT |
| [AppClassLoader@92e78c] info register classloader sun.misc.Launcher$AppClassLoader@92e78c |
| [AppClassLoader@92e78c] info using configuration /C:/temp/META-INF/aop.xml |
| [AppClassLoader@92e78c] info using configuration /C:/temp/META-INF/aop-ajc.xml |
| [AppClassLoader@92e78c] info register aspect ExceptionHandler |
| [AppClassLoader@92e78c] info processing reweavable type ExceptionHandler: ExceptionHandler.aj |
| </pre><div class="sect3"><a name="messages-scenarios-ltw-adviceNotWoven"></a><div class="titlepage"><div><h4 class="title"><a name="messages-scenarios-ltw-adviceNotWoven"></a>Advice not woven</h4></div></div><p> It is often difficult to determine, especially when using load-time weaving (LTW), |
| why advice has not been woven. Here is a quick guide to the messages to |
| look for. Firstly if you use the <tt>-verbose</tt> option you |
| should see the following message when your aspect is registered: </p><pre class="programlisting"> |
| info register aspect MyAspect |
| </pre><p> Secondly if you use the <tt>-debug</tt> option you should |
| see a message indicating that you class is being woven: </p><pre class="programlisting"> |
| debug weaving 'HelloWorld' |
| </pre><p> However this does not mean that advice has actually been woven into |
| your class; it says that the class has been passed to the weaver. To determine |
| whether your pointcuts match you can use the <tt>-showWeaveInfo</tt> |
| option which will cause a message to be issued each time a join point is woven: </p><pre class="programlisting"> |
| weaveinfo Join point 'method-execution(void HelloWorld.main(java.lang.String[]))' ... |
| </pre><p>If advice is woven at this join point you should get the |
| corresponding message.</p></div></div></div><div class="sect1"><a name="messages-xlint"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="messages-xlint"></a>Lint messages</h2></div></div><p> |
| The table below lists some useful <tt>-Xlint</tt> messages. </p><div class="informaltable" id="d0e265"><a name="d0e265"></a><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Message</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><tt>aspectExcludedByConfiguration</tt></td><td><tt>ignore</tt></td><td> |
| If an aspect is not being woven, despite being |
| registered, it could be that it has been excluded |
| by either an <tt>include</tt> or <tt>exclude</tt> |
| element in the |
| <tt>aspects</tt> section of <tt>META-INF/aop.xml</tt>. |
| Enable this message to determine whether an aspect has |
| been excluded. |
| </td></tr><tr><td><tt>adviceDidNotMatch</tt></td><td><tt>warning</tt></td><td> |
| Issued when advice did not potentially affect any join points. |
| This means the corresponding pointcut did not match any join |
| points in the program. This may be valid e.g., in library |
| aspects or code picking up error conditions, but often the |
| programmer simply made a mistake in the pointcut. The best |
| approach is to debug the pointcut. |
| </td></tr><tr><td><tt>invalidAbsoluteTypeName</tt></td><td><tt>warning</tt></td><td> |
| Issued when an exact type in a pointcut does not match any type |
| in the system. Note that this can interact with the rules for |
| resolving simple types, which permit unqualified names if they |
| are imported. |
| </td></tr><tr><td><tt>typeNotExposedToWeaver</tt></td><td><tt>warning</tt></td><td> |
| This means that a type which could be affected by an aspect |
| is not available for weaving. This happens when a class on |
| the classpath should be woven. |
| </td></tr><tr><td><tt>runtimeExceptionNotSoftened</tt></td><td><tt>warning</tt></td><td> |
| Before AspectJ 5, declare soft used to soften runtime exceptions |
| (unnecessarily). Since then, it does not but does issue this |
| warning in case the programmer did intend for the exception |
| to be wrapped. |
| </td></tr><tr><td><tt>unmatchedSuperTypeInCall</tt></td><td><tt>warning</tt></td><td> |
| Issued when a call pointcut specifies a defining type which |
| is not matched at the call site (where the declared type of |
| the reference is used, not the actual runtime type). Most |
| people should use |
| 'target(Foo) && call(void foo())' |
| instead. |
| </td></tr></tbody></table></div></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="pointcuts"></a>Chapter 2. Debugging Pointcuts</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#pointcuts-introduction">Introduction</a></dt><dt><a href="#pointcuts-debugging">Debugging pointcuts</a></dt></dl></div><div class="sect1"><a name="pointcuts-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="pointcuts-introduction"></a>Introduction</h2></div></div><p> |
| This section describes how to write and debug pointcuts |
| using the usual approach of iteration and decomposition. |
| New users are often stumped when their advice does not match. |
| That means the pointcut doesn't match; they rewrite the |
| pointcut and it still doesn't match, with no new information. |
| This can be frustrating if each iteration involves building, |
| deploying, and testing a complex application. Learning to |
| break it down, particularly into parts that can be checked |
| at compile-time, can save a lot of time. |
| </p></div><div class="sect1"><a name="pointcuts-debugging"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="pointcuts-debugging"></a>Debugging pointcuts</h2></div></div><p> |
| Go at it top-down and then bottom-up. Top-down, draft significant |
| aspects by first writing the comments to specify responsibilities. |
| Advice responsibility usually takes the form, "When X, do Y." |
| Pointcut responsibility for "When X" often takes the form, |
| "When [join points] [in locations] [are ...]". These []'s often |
| translate to named pointcuts (like `libraryCalls() && within(Client) |
| && args(Context)`) which form a semantic bridge to the plain-text |
| meaning in a comment (e.g., `// when the client passes only context into |
| the library`). |
| This gets you to a point where you can debug the parts of the |
| pointcut independently. |
| </p><p> |
| Bottom up (to build each part), consider each primitive pointcut |
| designator (PCD), then the composition, and then any implicit |
| constraints: |
| <div class="orderedlist"><ol type="1"><li><p><a name="d0e358"></a> |
| What kinds of join points should it match? (constructor-call? |
| field-get?)? This translates to using the kinded pointcuts |
| (`call(..)`, `get(..)`, etc.). |
| </p></li><li><p><a name="d0e361"></a> |
| Are these restricted to being lexically within something? This |
| translates to using `within{code}(..)`. If this is true, it should |
| always be used, to speed up weaving. |
| </p></li><li><p><a name="d0e364"></a> |
| What runtime constraints and context should be true and available at |
| each join point? This translates to `this()`, `target()`, `args()`, |
| `cflow{below}()` and `if(..)`. |
| </p></li><li><p><a name="d0e367"></a> |
| Are there any advice or implementation limitations at issue? This |
| involves knowing the few constraints on AspectJ imposed by Java bytecode |
| as listed in the AspectJ Programming Guide section on |
| <a href="../progguide/implementation.html" target="_top">Implementation Notes</a>. |
| </p></li></ol></div> |
| </p><p> |
| It's much faster to iterate a pointcut at compile-time |
| using declare warning (even better, some errors are identified |
| at parse-time in the latest versions of AJDT). |
| Start with the parts of the pointcut |
| that are staticly-determinable (i.e., they do not involve |
| the runtime PCD's listed above). If compiles themselves |
| take too long because of all the AspectJ weaving, then |
| try to only include the debugging aspect with the prototype |
| pointcut, and limit the scope using <tt>within(..)</tt>. |
| </p><p> |
| Some mistakes in primitive pointcuts: |
| <div class="itemizedlist"><ul><li><p><a name="d0e382"></a> |
| `this(Foo) && execution(static * *(..))`: There is no `this` in a static |
| context, so `this()` or `target()` should not be used in a static |
| context or when targetting a static context (respectively). This |
| happens most often when you want to say things like "all calls to Foo from Bar" |
| and you only pick out calls to instance methods of Foo |
| or you try to pick out calls from static methods of Bar. |
| </p></li><li><p><a name="d0e385"></a> |
| `target(Foo) && call(new(..)`: This will never match. In |
| constructor-call join points, there is no target because the object |
| has not been created yet. |
| </p></li><li><p><a name="d0e388"></a> |
| `call(* Foo.*(..))`: `Foo` refers to the compile-time type of the |
| invoking reference, not the implementing class. In Java before 1.4, |
| the compile-time type was rendered as the defining type, not the |
| reference type; this was corrected in 1.4 (as shown when using ajc |
| with the -1.4 flag) Most people should use `target(Foo) && call(...)`. |
| </p></li><li><p><a name="d0e391"></a> |
| `execution(* Foo.bar(..))`: An execution join point for Foo is |
| always within Foo, so this won't pick out any overrides of bar(..). |
| Use `target(Foo) && execution(* bar(..))` for instance methods. |
| </p></li><li><p><a name="d0e394"></a> |
| `within(Foo)`: anonymous types are not known at weave-time to be |
| within the lexically-enclosing type (a limitation of Java bytecode). |
| </p></li></ul></div> |
| </p><p> |
| Some mistakes in composition: |
| <div class="itemizedlist"><ul><li><p><a name="d0e401"></a> |
| `call(* foo(Bar, Foo)) && args(Foo)`: This will never match. |
| The parameters in `args(..)` are position-dependent, so `args(Foo)` only picks |
| out join points where there is only one argument possible, of type Foo. |
| Use the indeterminate-arguments operator '..' as needed, e.g., `args(Foo, ..)`. |
| </p></li><li><p><a name="d0e404"></a> |
| `call(* foo()) && execution(* foo())`: This will never match. Each |
| pointcut must be true at each join point matched. For a union of different |
| kinds of join points (here, call or execution), use '||'. |
| E.g., to match both method-call and field-get join points, use |
| `call(* ...) || get(...)`. |
| </p></li></ul></div> |
| </p><p> |
| Some mistakes in implicit advice constraints: |
| <div class="itemizedlist"><ul><li><p><a name="d0e411"></a> |
| `after () returning (Foo foo) : ...`: after advice can bind the |
| returned object or exception thrown. That effectively acts like |
| `target()`, `this()`, or `args()` in restricting when the advice |
| runs based on the runtime type of the bound object, even though it is |
| not explicitly part of the pointcut. |
| </p></li></ul></div> |
| </p><p> |
| Some mistakes in implementation requirements: |
| <div class="itemizedlist"><ul><li><p><a name="d0e418"></a> |
| `ajc` has to control the code for a join point in order to implement |
| the join point. This translates to an implicit `within({code under |
| the control of the compiler})` for all join points, with additional |
| caveat for some join points. Take exception handlers, for example: |
| there is no way to be sure from the bytecode where the original handler |
| ends, so `ajc` can't implement after advice on handler join points. |
| (Since these are on a per-join-point basis, they should be considered |
| for each corresponding primitive pointcut designator.) Unlike the |
| mistakes with the primitive PCDs above, the compiler will emit an |
| error for these caveats. |
| </p></li><li><p><a name="d0e421"></a> |
| `call(@SuperAnnotation Subclass.meth()`: Annotations are not inherited |
| by default, so e.g., if the pointcut specifies an annotation, then |
| subclass implementations of that method will not be matched. |
| </p></li></ul></div> |
| </p></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="ajcore"></a>Chapter 3. AspectJ Core Files</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#ajcore-introduction">Introduction</a></dt><dd><dl><dt><a href="#configuration">Configuring dump files</a></dt><dt><a href="#ajcore-examples">AJCore File Examples</a></dt></dl></dd></dl></div><div class="sect1"><a name="ajcore-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="ajcore-introduction"></a>Introduction</h2></div></div><p> When the compiler terminates abnormally, either because a particular kind of message was |
| issued or an exception was thrown, an AspectJ core file will be produced. You will |
| find it the working directory of the compiler and it will have a name that contains |
| the date and time that the file was produced |
| e.g. <tt>ajcore.20060810.173655.626.txt</tt>. The file contains details |
| of the problem such as the exception thrown as well as information about the |
| environment such as operating system and Java version. When submitting a bug, |
| include this file whenever it is available.</p><div class="sect2"><a name="configuration"></a><div class="titlepage"><div><h3 class="title"><a name="configuration"></a>Configuring dump files</h3></div></div><p> By default AspectJ will only create an <tt>ajcore</tt> file |
| when an unexpected exception is thrown by the weaver or an |
| <tt>abort</tt> message is |
| issued. However it is possible to disable this feature or enable files to |
| be produced under different circumstances. The table below lists the System |
| properties that can be used to configure <tt>ajcore</tt> files. </p><div class="informaltable" id="d0e450"><a name="d0e450"></a><table border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Property</th><th>Default</th><th>Description</th></tr></thead><tbody><tr><td><tt>org.aspectj.weaver.Dump.exception</tt></td><td><tt>true</tt></td><td> |
| Generate an <tt>ajcore</tt> files when an exception thrown. |
| </td></tr><tr><td><tt>org.aspectj.weaver.Dump.condition</tt></td><td><tt>abort</tt></td><td> |
| Message kind for which to generate <tt>ajcore</tt> |
| e.g. <tt>error</tt>. |
| </td></tr><tr><td><tt>org.aspectj.dump.directory</tt></td><td><tt>none</tt></td><td> |
| The directory used for ajcore files. |
| </td></tr></tbody></table></div></div><div class="sect2"><a name="ajcore-examples"></a><div class="titlepage"><div><h3 class="title"><a name="ajcore-examples"></a>AJCore File Examples</h3></div></div><p> Below is an extract from an <tt>ajcore</tt> file. You will see |
| details of the dump configuration as well as the exception (with stack trace) that |
| is the source of the problem and any messages issued by the compiler. Most importantly |
| the exact version of AspectJ is included. </p><pre class="programlisting"> |
| ---- AspectJ Properties --- |
| AspectJ Compiler DEVELOPMENT built on Tuesday Jul 25, 2006 at 13:00:09 GMT |
| ---- Dump Properties --- |
| Dump file: ajcore.20060810.173655.626.txt |
| Dump reason: java.lang.NoClassDefFoundError |
| Dump on exception: true |
| Dump at exit condition: abort |
| ---- Exception Information --- |
| java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory |
| at org.aspectj.weaver.tools.CommonsTraceFactory.<init>(CommonsTraceFactory.java:17) |
| at java.lang.Class.newInstance0(Native Method) |
| at java.lang.Class.newInstance(Class.java:232) |
| at org.aspectj.weaver.tools.TraceFactory.<clinit>(TraceFactory.java:35) |
| at org.aspectj.weaver.World.<clinit>(World.java:114) |
| at org.aspectj.ajdt.internal.core.builder.AjBuildManager.initBcelWorld(AjBuildManager.java:679) |
| at org.aspectj.ajdt.internal.core.builder.AjBuildManager.doBuild(AjBuildManager.java:224) |
| at org.aspectj.ajdt.internal.core.builder.AjBuildManager.batchBuild(AjBuildManager.java:164) |
| at org.aspectj.ajdt.ajc.AjdtCommand.doCommand(AjdtCommand.java:112) |
| at org.aspectj.ajdt.ajc.AjdtCommand.runCommand(AjdtCommand.java:60) |
| at org.aspectj.tools.ajc.Main.run(Main.java:367) |
| at org.aspectj.tools.ajc.Main.runMain(Main.java:246) |
| at org.aspectj.tools.ajc.Main.main(Main.java:86) |
| ---- System Properties --- |
| java.runtime.name=Java(TM) 2 Runtime Environment, Standard Edition |
| sun.boot.library.path=C:\jdk1.3.1_16\jre\bin |
| java.vm.version=1.3.1_16-b06 |
| java.vm.vendor=Sun Microsystems Inc. |
| java.vendor.url=http://java.sun.com/ |
| path.separator=; |
| java.vm.name=Java HotSpot(TM) Client VM |
| file.encoding.pkg=sun.io |
| java.vm.specification.name=Java Virtual Machine Specification |
| user.dir=C:\workspaces\org.aspectj\org.aspectj.ant.tests |
| java.runtime.version=1.3.1_16-b06 |
| java.awt.graphicsenv=sun.awt.Win32GraphicsEnvironment |
| os.arch=x86 |
| java.io.tmpdir=C:\DOCUME~1\IBM_user\LOCALS~1\Temp\ |
| line.separator= |
| |
| java.vm.specification.vendor=Sun Microsystems Inc. |
| java.awt.fonts= |
| os.name=Windows XP |
| java.library.path=C:\jdk1.3.1_16\jre\bin;... |
| java.specification.name=Java Platform API Specification |
| java.class.version=47.0 |
| os.version=5.1 |
| user.home=C:\Documents and Settings\IBM_user |
| user.timezone=Europe/London |
| java.awt.printerjob=sun.awt.windows.WPrinterJob |
| file.encoding=Cp1252 |
| java.specification.version=1.3 |
| java.class.path=C:\workspaces\org.aspectj\aj-build\dist\tools\lib\aspectjtools.jar |
| user.name=IBM_user |
| java.vm.specification.version=1.0 |
| java.home=C:\jdk1.3.1_16\jre |
| user.language=en |
| java.specification.vendor=Sun Microsystems Inc. |
| awt.toolkit=sun.awt.windows.WToolkit |
| java.vm.info=mixed mode |
| java.version=1.3.1_16 |
| java.ext.dirs=C:\jdk1.3.1_16\jre\lib\ext |
| sun.boot.class.path=C:\jdk1.3.1_16\jre\lib\rt.jar;... |
| java.vendor=Sun Microsystems Inc. |
| file.separator=\ |
| java.vendor.url.bug=http://java.sun.com/cgi-bin/bugreport.cgi |
| sun.io.unicode.encoding=UnicodeLittle |
| sun.cpu.endian=little |
| user.region=GB |
| sun.cpu.isalist=pentium i486 i386 |
| ---- Command Line --- |
| -d |
| C:\workspaces\org.aspectj\org.aspectj.ant.tests\IncrementalAjcTaskTest-temp |
| -g:none |
| -deprecation |
| -noExit |
| -warn:-unusedImport |
| -nowarn |
| -XterminateAfterCompilation |
| -preserveAllLocals |
| -proceedOnError |
| -referenceInfo |
| -source |
| 1.3 |
| -target |
| 1.1 |
| -time |
| -verbose |
| -classpath |
| C:\workspaces\org.aspectj\org.aspectj.ant.tests\..\lib\test\aspectjrt.jar |
| -argfile |
| C:\workspaces\org.aspectj\taskdefs\testdata\default.lst |
| -messageHolder |
| org.aspectj.bridge.MessageHandler |
| ---- Full Classpath --- |
| Empty |
| ---- Compiler Messages --- |
| abort ABORT -- (NoClassDefFoundError) org/apache/commons/logging/LogFactory |
| org/apache/commons/logging/LogFactory |
| java.lang.NoClassDefFoundError: org/apache/commons/logging/LogFactory |
| at org.aspectj.weaver.tools.CommonsTraceFactory.<init>(CommonsTraceFactory.java:17) |
| at java.lang.Class.newInstance0(Native Method) |
| at java.lang.Class.newInstance(Class.java:232) |
| at org.aspectj.weaver.tools.TraceFactory.<clinit>(TraceFactory.java:35) |
| at org.aspectj.weaver.World.<clinit>(World.java:114) |
| at org.aspectj.ajdt.internal.core.builder.AjBuildManager.initBcelWorld(AjBuildManager.java:679) |
| at org.aspectj.ajdt.internal.core.builder.AjBuildManager.doBuild(AjBuildManager.java:224) |
| at org.aspectj.ajdt.internal.core.builder.AjBuildManager.batchBuild(AjBuildManager.java:164) |
| at org.aspectj.ajdt.ajc.AjdtCommand.doCommand(AjdtCommand.java:112) |
| at org.aspectj.ajdt.ajc.AjdtCommand.runCommand(AjdtCommand.java:60) |
| at org.aspectj.tools.ajc.Main.run(Main.java:367) |
| at org.aspectj.tools.ajc.Main.runMain(Main.java:246) |
| at org.aspectj.tools.ajc.Main.main(Main.java:86) |
| </pre></div></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="trace"></a>Chapter 4. Tracing</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#trace-introduction">Introduction</a></dt><dd><dl><dt><a href="#trace-configuration">Configuring Tracing</a></dt><dt><a href="#trace-examples">Examples</a></dt></dl></dd></dl></div><div class="sect1"><a name="trace-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="trace-introduction"></a>Introduction</h2></div></div><p> |
| The AspectJ developers have instrumented the compiler/weaver with |
| many "trace" messages for their own debugging use. These remain in |
| the production releases because tracing helps when it is hard to |
| isolate the problem in a test case. This sections describes how |
| to enable tracing so you can provide trace information on bug reports. |
| </p><p> |
| The usual approach to opening a report on Bugzilla is to describe the symptoms of the |
| problem and attach a simple testcase. This allows the AspectJ team to try and reproduce the problem in |
| an attempt to fix it as well as improve the test suite. Unfortunately it may not be possible |
| to produce such a testcase either because your program is too large or is commercially sensitive. Alternatively |
| the problem may relate to your specific environment where AspectJ is being used and will not be |
| reproducible by the AspectJ team. In each of these situations you can produce a |
| trace of the compiler when the problem occurs instead. This can then be attached to the bug report. </p><div class="sect2"><a name="trace-configuration"></a><div class="titlepage"><div><h3 class="title"><a name="trace-configuration"></a>Configuring Tracing</h3></div></div><p> When available (Java 5 or later) AspectJ will use the |
| <a href="http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html" target="_top"> |
| java.util.logging</a> infrastructure |
| configured using a <tt>logging.properties</tt> file. By default only error |
| and fatal events will be logged but less severe warnings as well as fine-grained |
| method entry and exit events can be obtained using the appropriate configuration. All |
| regular compiler messages can also be logged through the infrastructure by setting the |
| <tt>org.aspectj.weaving.messages</tt> System property. </p><p> If you are running the AspectJ compiler/weaver under JDK 1.4 or earlier, |
| AspectJ will use a simple built-in trace |
| infrastructure that logs to stderr. This is enabled by setting the |
| <tt>org.aspectj.weaving.tracing.enabled</tt> System property. You may also override |
| the default behaviour or provide your own trace implementation using the |
| <tt>org.aspectj.weaving.tracing.factory</tt> System property. </p><p> The table below lists the System properties that can be used to configure tracing. </p><div class="informaltable" id="d0e541"><a name="d0e541"></a><table border="1"><colgroup><col><col></colgroup><thead><tr><th>Property</th><th>Description</th></tr></thead><tbody><tr><td><tt>org.aspectj.tracing.debug</tt></td><td> |
| Enable simple debugging of the trace infrastructure itself. |
| <p> Default: <tt>false</tt>. </p></td></tr><tr><td><tt>org.aspectj.tracing.enabled</tt></td><td> |
| Enable the built-in AspectJ trace infrastructure. |
| <p> Default: <tt>false</tt>. </p></td></tr><tr><td><tt>org.aspectj.tracing.factory</tt></td><td> |
| Select trace infrastructure. Specify the fully qualified class name |
| of the <tt>org.aspectj.weaver.tools.TraceFactory</tt> |
| interface to use a custom infrastructure. Specify a value of |
| <tt>default</tt> to force AspectJ to use it's |
| built-in infrastructure. |
| </td></tr><tr><td><tt>org.aspectj.tracing.messages</tt></td><td> |
| Enable tracing of compiler messages. The kind of messages logged |
| is determined by the selected trace infrastructure not the message |
| configuration. |
| <p> Default: <tt>false</tt>. </p></td></tr></tbody></table></div></div><div class="sect2"><a name="trace-examples"></a><div class="titlepage"><div><h3 class="title"><a name="trace-examples"></a>Examples</h3></div></div><p> Using <tt>-Dorg.aspectj.tracing.factory=default</tt> |
| to force AspectJ to use its internal infrastructure, |
| <tt>-Dorg.aspectj.tracing.enabled=true</tt> to turn it on and |
| <tt>-Dorg.aspectj.tracing.messages=true</tt> to include messages |
| running a simple HelloWorld with LTW will generate tracing to stderr. Below |
| is an extract from that trace with method arguments removed. |
| You will notice the millisecond time stamp, |
| thread id and indication of entry/exit/event or message type for each line |
| of trace. |
| </p><pre class="programlisting"> |
| 15:44:18.630 main > org.aspectj.weaver.loadtime.Aj.<init> |
| 15:44:18.660 main < org.aspectj.weaver.loadtime.Aj.<init> |
| 15:44:18.660 main > org.aspectj.weaver.loadtime.Aj.preProcess |
| 15:44:18.660 main - org.aspectj.weaver.loadtime.Aj.preProcess |
| 15:44:18.730 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.<init> |
| 15:44:18.730 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.<init> |
| 15:44:18.730 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.initialize |
| 15:44:18.821 main I [AppClassLoader@92e78c] info AspectJ Weaver Version DEVELOPMENT ... |
| 15:44:18.821 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions |
| 15:44:18.821 main I [AppClassLoader@92e78c] info register classloader ... |
| 15:44:18.821 main - org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions |
| 15:44:18.841 main - org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions |
| 15:44:18.841 main I [AppClassLoader@92e78c] info using configuration ... |
| 15:44:18.891 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.parseDefinitions |
| 15:44:19.021 main > org.aspectj.weaver.World$TypeMap.<init> |
| 15:44:19.021 main < org.aspectj.weaver.World$TypeMap.<init> |
| 15:44:19.021 main > org.aspectj.weaver.CrosscuttingMembersSet.<init> |
| 15:44:19.021 main < org.aspectj.weaver.CrosscuttingMembersSet.<init> |
| 15:44:19.021 main > org.aspectj.weaver.Lint.<init> |
| 15:44:19.021 main < org.aspectj.weaver.Lint.<init> |
| 15:44:19.021 main > org.aspectj.weaver.World.<init> |
| 15:44:19.111 main < org.aspectj.weaver.World.<init> |
| 15:44:19.201 main > org.aspectj.weaver.bcel.BcelWeaver.<init> |
| 15:44:19.201 main < org.aspectj.weaver.bcel.BcelWeaver.<init> |
| 15:44:19.201 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerDefinitions |
| 15:44:19.211 main > org.aspectj.weaver.bcel.BcelWeaver.setReweavableMode |
| 15:44:19.351 main < org.aspectj.weaver.bcel.BcelWeaver.setReweavableMode |
| 15:44:19.351 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerAspects |
| 15:44:19.351 main I [AppClassLoader@92e78c] info register aspect Aspect |
| 15:44:19.351 main > org.aspectj.weaver.bcel.BcelWeaver.addLibraryAspect |
| 15:44:19.501 main - org.aspectj.weaver.bcel.BcelWorld.lookupJavaClass |
| 15:44:19.632 main > org.aspectj.weaver.CrosscuttingMembersSet.addOrReplaceAspect |
| 15:44:19.792 main < org.aspectj.weaver.CrosscuttingMembersSet.addOrReplaceAspect |
| 15:44:19.792 main < org.aspectj.weaver.bcel.BcelWeaver.addLibraryAspect |
| 15:44:19.792 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerAspects |
| 15:44:19.792 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.registerDefinitions |
| 15:44:19.792 main > org.aspectj.weaver.bcel.BcelWeaver.prepareForWeave |
| 15:44:19.822 main < org.aspectj.weaver.bcel.BcelWeaver.prepareForWeave |
| 15:44:19.822 main > org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.weaveAndDefineConcete... |
| 15:44:19.822 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.weaveAndDefineConcete... |
| 15:44:19.822 main < org.aspectj.weaver.loadtime.ClassLoaderWeavingAdaptor.initialize |
| 15:44:19.822 main > org.aspectj.weaver.tools.WeavingAdaptor.weaveClass |
| ... |
| </pre><p> Alternatively when running under Java 5 the <tt>logging.properties</tt> |
| file below could be used to configure Java Logging. The resulting |
| file, just containing trace for the |
| <tt>org.aspectj.weaver.loadtime</tt> package, will be |
| written to <tt>java0.log</tt> in your <tt>user.home</tt> directory. |
| </p><pre class="programlisting"> |
| handlers= java.util.logging.FileHandler |
| |
| .level= INFO |
| |
| java.util.logging.FileHandler.pattern = %h/java%u.log |
| java.util.logging.FileHandler.count = 1 |
| java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter |
| java.util.logging.FileHandler.level = FINER |
| |
| org.aspectj.weaver.loadtime.level = FINER |
| </pre><p> |
| By setting the System property <tt>-Dorg.aspectj.tracing.debug=true</tt> |
| you should see a message confirming which trace infrastructure is being used. |
| </p><pre class="programlisting"> |
| TraceFactory.instance=org.aspectj.weaver.tools.Jdk14TraceFactory@12dacd1 |
| </pre></div></div></div><div class="chapter"><div class="titlepage"><div><h2 class="title"><a name="ltwdump"></a>Chapter 5. Dumping classes during load-time weaving</h2></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="#ltwdump-introduction">Introduction</a></dt><dd><dl><dt><a href="#ltw-examples">Configuring bytecode dumping in load-time weaving</a></dt><dt><a href="#ltwdump-examples">LTW Dump Examples</a></dt></dl></dd></dl></div><div class="sect1"><a name="ltwdump-introduction"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="ltwdump-introduction"></a>Introduction</h2></div></div><p> |
| Very rarely problems may be encountered with classes that have been |
| load-time woven. |
| Symptoms will include incorrect program function or a Java exception such as |
| <tt>java.lang.VerifyError</tt>. |
| In these situations it's most helpful to include the offending class |
| in the bug report. When using load-time weaving the woven classes are |
| in memory only so to save them to disk configure |
| <tt>META-INF/aop.xml</tt> to dump the classes (by default |
| to an <tt>_ajdump</tt> subdirectory of the current working |
| directory). Also if the input class file is not available |
| (e.g. it is a generated proxy or has already been instrumented by another agent) |
| you can configure the weaver to dump the input classes as well. |
| </p><div class="sect2"><a name="ltw-examples"></a><div class="titlepage"><div><h3 class="title"><a name="ltw-examples"></a>Configuring bytecode dumping in load-time weaving</h3></div></div><p> |
| For details of how to configure byte-code dumping, see the |
| AspectJ Development Environment Guide section on |
| <a href="../devguide/ltw-configuration.html#configuring-load-time-weaving-with-aopxml-files" target="_top"> |
| Configuring Load-time Weaving</a>. |
| Following is a simple example. |
| </p></div><div class="sect2"><a name="ltwdump-examples"></a><div class="titlepage"><div><h3 class="title"><a name="ltwdump-examples"></a>LTW Dump Examples</h3></div></div><p> The following <tt>META-INF/aop.xml</tt> will |
| weave classes in the <tt>com.foo</tt> package (and subpackages) but not |
| CGLIB generated classes in the <tt>com.foo.bar</tt> package (and subpackages). |
| It will also ensure all |
| woven byte-code is dumped both before and after weaving. </p><pre class="programlisting"> |
| <aspectj> |
| <aspects> |
| <aspect name="ataspectj.EmptyAspect"/> |
| </aspects> |
| <weaver options="-verbose -debug"> |
| <dump within="com.foo.bar..*" beforeandafter="true"/> |
| <include within="com.foo..*"/> |
| <exclude within="com.foo.bar..*CGLIB*"/> |
| </weaver> |
| </aspectj> |
| </pre><p> You should see messages similar to this: </p><pre class="programlisting"> |
| [WeavingURLClassLoader] info AspectJ Weaver Version 1.5.3 built on Thursday Oct 26, 2006 at 17:22:31 GMT |
| [WeavingURLClassLoader] info register classloader org.aspectj.weaver.loadtime.WeavingURLClassLoader |
| [WeavingURLClassLoader] info using configuration /C:/tempMETA-INF/aop.xml |
| [WeavingURLClassLoader] info register aspect ataspectj.EmptyAspect |
| [WeavingURLClassLoader] debug not weaving 'com.foo.bar.Test$$EnhancerByCGLIB$$12345' |
| [WeavingURLClassLoader] debug weaving 'com.foo.bar.Test' |
| </pre><p> On disk you would find the following files: </p><pre class="programlisting"> |
| _ajdump/_before/com/foo/bar/Test.class |
| _ajdump/com/foo/bar/Test.class |
| </pre></div></div></div></div></body></html> |
