123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385 |
- <chapter id="messages" xreflabel="Messages">
- <title>Messages</title>
-
- <sect1 id="messages-introduction">
- <title>Introduction</title>
- <para>
- 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.
- </para>
- <sect2 id="messages-introduction-config"
- xreflabel="messages-configuration">
- <title>Configuring Messages</title>
- <para>
- The compiler offers <literal>-verbose</literal>,
- <literal>-warning</literal>, and <literal>-XLint</literal> 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
- <ulink url="../devguide/ajc-ref.html">Ajc</ulink> and
- <ulink url="../devguide/antTasks-iajc.html">Ant Tasks</ulink>.
- The <ulink url="../devguide/ltw.html">Load-time Weaving</ulink>
- 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 <literal>-verbose</literal> option has the effect of including
- messages level "info", which are normally ignored.
- Both <literal>warning</literal> and <literal>XLint</literal>
- 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.
- </para>
-
- <para> 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
- <ulink url="../devguide/ajc-ref.html">ajc</ulink>,
- <ulink url="../devguide/antTasks.html">Ant</ulink> or
- <ulink url="../devguide/ltw-configuration.html#weaver-options">LTW</ulink>.
- </para>
-
- <para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Option</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>-verbose</literal>
- </entry>
- <entry>
- Show informational messages including AspectJ version
- and build date.
- </entry>
- </row>
- <row>
- <entry>
- <literal>-debug</literal>
- </entry>
- <entry>
- (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.)
- </entry>
- </row>
- <row>
- <entry>
- <literal>-showWeaveInfo</literal>
- </entry>
- <entry>
- Show weaving messages.
- </entry>
- </row>
- <row>
- <entry>
- <literal>-Xlint</literal>
- </entry>
- <entry>
- Control level of lint messages.
- </entry>
- </row>
- <row>
- <entry>
- <literal>messageHolderClass</literal>/
- <literal>-XmessageHolderClass:</literal>
- </entry>
- <entry>
- In Ant tasks and LTW respectively specify the class to receive all messages.
- See
- <ulink url="../devguide/antTasks-iajc.html#antTasks-iajc-options">
- iajc task options</ulink> or
- <ulink url="../devguide/ltw-configuration.html#weaver-options">
- Weaver Options</ulink>.
- </entry>
- </row>
-
- <!-- We need full javadoc for this API
- <row>
- <entry>
- <literal>org.aspectj.tools.Main.setMessageHolder(..)</literal>
- </entry>
- <entry>
- Programmatic access for setting the message holder
- outside of Ant.
- </entry>
- </row>
- -->
- </tbody>
- </tgroup>
- </informaltable>
- </para>
-
- <para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>System Property</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>aj.weaving.verbose</literal>
- </entry>
- <entry>
- Show informational messages including AspectJ version and build date
- (same as <literal>-verbose</literal> option).
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.aspectj.weaver.showWeaveInfo</literal>
- </entry>
- <entry>
- Show weaving messages
- (same as <literal>-showWeaveInfo</literal> option).
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.aspectj.weaving.messages</literal>
- </entry>
- <entry>
- Set this system property to enable tracing of all compiler
- messages. See <xref linkend="trace-configuration"/>.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
-
- <para>
- <informaltable>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Annotation</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>@SuppressAjWarnings</literal>
- </entry>
- <entry>
- Include this is Java 5 code to suppress AspectJ
- warnings associated with the next line of code.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </para>
-
- </sect2>
- </sect1>
- <sect1 id="messages-scenarios">
- <title>Message scenarios</title>
-
- <sect2 id="messages-scenarios-ct">
- <title>Compile-time weaving scenarios</title>
- <sect3 id="messages-scenarios-ct-adviceNotWoven">
- <title>Advice not woven</title>
- <para>This means that the pointcut for the advice did not match,
- and it should be debugged as described in
- <xref linkend="pointcuts"/>.</para>
- </sect3>
- </sect2>
-
- <sect2 id="messages-scenarios-ltw">
- <title>Load-time weaving scenarios</title>
-
- <para> You can use <literal>META-INF/aop.xml</literal> 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. </para>
-
- <programlisting><![CDATA[
- <aspectj>
- <weaver options="-verbose">
- </weaver>
- </aspectj>
- ]]></programlisting>
-
- <para>The messages indicate which <literal>META-INF/aop.xml</literal>
- 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. </para>
-
- <programlisting><![CDATA[
- [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
- ]]></programlisting>
-
- <sect3 id="messages-scenarios-ltw-adviceNotWoven">
- <title>Advice not woven</title>
- <para> 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 <literal>-verbose</literal> option you
- should see the following message when your aspect is registered: </para>
-
- <programlisting><![CDATA[
- info register aspect MyAspect
- ]]></programlisting>
-
- <para> Secondly if you use the <literal>-debug</literal> option you should
- see a message indicating that you class is being woven: </para>
-
- <programlisting><![CDATA[
- debug weaving 'HelloWorld'
- ]]></programlisting>
-
- <para> 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 <literal>-showWeaveInfo</literal>
- option which will cause a message to be issued each time a join point is woven: </para>
-
- <programlisting><![CDATA[
- weaveinfo Join point 'method-execution(void HelloWorld.main(java.lang.String[]))' ...
- ]]></programlisting>
-
- <para>If advice is woven at this join point you should get the
- corresponding message.</para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="messages-xlint">
- <title>Lint messages</title>
- <para>
- The table below lists some useful <literal>-Xlint</literal> messages. </para>
- <informaltable>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Message</entry>
- <entry>Default</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>aspectExcludedByConfiguration</literal>
- </entry>
- <entry>
- <literal>ignore</literal>
- </entry>
- <entry>
- If an aspect is not being woven, despite being
- registered, it could be that it has been excluded
- by either an <literal>include</literal> or <literal>exclude</literal>
- element in the
- <literal>aspects</literal> section of <literal>META-INF/aop.xml</literal>.
- Enable this message to determine whether an aspect has
- been excluded.
- </entry>
- </row>
- <row>
- <entry>
- <literal>adviceDidNotMatch</literal>
- </entry>
- <entry>
- <literal>warning</literal>
- </entry>
- <entry>
- 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.
- </entry>
- </row>
- <row>
- <entry>
- <literal>invalidAbsoluteTypeName</literal>
- </entry>
- <entry>
- <literal>warning</literal>
- </entry>
- <entry>
- 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.
- </entry>
- </row>
- <row>
- <entry>
- <literal>typeNotExposedToWeaver</literal>
- </entry>
- <entry>
- <literal>warning</literal>
- </entry>
- <entry>
- 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.
- </entry>
- </row>
- <row>
- <entry>
- <literal>runtimeExceptionNotSoftened</literal>
- </entry>
- <entry>
- <literal>warning</literal>
- </entry>
- <entry>
- 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.
- </entry>
- </row>
- <row>
- <entry>
- <literal>unmatchedSuperTypeInCall</literal>
- </entry>
- <entry>
- <literal>warning</literal>
- </entry>
- <entry>
- 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.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </sect1>
-
- </chapter>
|