org.aspectj/docs/pdGuideDB/messages.xml

<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) &amp;&amp; call(void foo())'
                                instead.
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </informaltable>
    </sect1>

</chapter>