org.aspectj/docs/pdGuideDB/pdguide.xml

<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1//EN"
                      "../../lib/docbook/docbook-dtd/docbookx.dtd"
[
<!ENTITY messages               SYSTEM "messages.xml">
<!ENTITY pointcuts              SYSTEM "pointcuts.xml">
<!ENTITY trace                  SYSTEM "trace.xml">
<!ENTITY ajcore                 SYSTEM "ajcore.xml">
<!ENTITY ltwdump                SYSTEM "ltwdump.xml">
]>

<book>
  <bookinfo>
    <title>The AspectJ<superscript>tm</superscript> Problem Diagnosis Guide</title>

    <authorgroup>
      <author>
        <othername>the AspectJ Team</othername>
      </author>
    </authorgroup>

      <legalnotice>
        <para>Copyright (c) 2006 IBM Corporation and others.
         2006 Contributors.  
         All rights reserved.
        </para>
      </legalnotice>

    <abstract>
      <para>
          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.
      </para>
      <para>
          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 <xref linkend="messages"/>.  Since most errors
          relate to writing pointcuts incorrectly, there is a section on 
          <xref linkend="pointcuts"/>.
      </para>
      <para>
          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: 
        <orderedlist>
            <listitem><para><xref linkend="trace"/> can be enabled to track progress up to the time of a failure;</para></listitem>
            <listitem><para><xref linkend="ajcore"/> can give a relatively complete picture of the state of 
          the world at the time of a failure; and </para></listitem>
            <listitem><para><xref linkend="ltwdump"/> is a way to capture both 
                input and output classes during load-time weaving.
          </para></listitem>
        </orderedlist>
          </para>
      <para>
          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.   
      </para>        
    </abstract>            
  </bookinfo>
  
  &messages;
  &pointcuts;
  &ajcore;
  &trace;
  &ltwdump;

</book>