org.aspectj/docs/faq/faq.xml

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

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  "../../lib/docbook/docbook-dtd/docbookx.dtd">

<!-- set style sheet in build.xml using xml-html-stylesheet variable -->
<!-- `copy-to-register' (C-x r s) then `insert-register' (C-x r i).
      <qandaentry>
        <question id="q:XX" xreflabel="Q:XX">
          <para></para>
        </question>

        <answer>
          <para></para>
        </answer>
      </qandaentry>
-->
<article class="faq">
  <title>Frequently Asked Questions about AspectJ</title>
  <para>Copyright (c) 1997-2001 Xerox Corporation, 
       2002 Palo Alto Research Center, Incorporated,
       2003-2006 Contributors. All rights reserved.
  </para>
  <!-- todo Update me! -->
  <para>Last updated November 3, 2006
  </para>
  <para>
   For a list of recently-updated FAQ entries, see <xref linkend="q:faqchanges"/>
  </para>
  <qandaset defaultlabel="number">
    <qandadiv id="overview" xreflabel="Overview">
      <title>Overview</title>
      <qandaentry>
        <question id="q:whatisaj" xreflabel="Q:What is AspectJ?">
          <para>What is AspectJ?</para>
        </question>
        <answer>
          <para>
            AspectJ(tm) is a simple and practical extension to the 
            Java(tm) programming
            language that adds to Java aspect-oriented programming (AOP)
            capabilities. AOP allows developers to reap the benefits of
            modularity for concerns that cut across the natural units of
            modularity. In object-oriented programs like Java, the natural unit
            of modularity is the class. In AspectJ, aspects modularize concerns that
            affect more than one class.  
	  </para>
          <para>You compile your program using the AspectJ compiler 
          (perhaps using the supported development environments) 
          and then run it, 
          supplying a small (&lt; 100K) runtime library.
          </para>
          <para>The AspectJ technologies include 
           a compiler (<literal>ajc</literal>), 
           a debugger (<literal>ajdb</literal>), 
           a documentation generator (<literal>ajdoc</literal>), 
           a program structure browser (<literal>ajbrowser</literal>), 
           and integration with
            Eclipse, Sun-ONE/Netbeans, GNU Emacs/XEmacs, 
            JBuilder, and Ant.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:benefits"
            xreflabel="Q:What are the benefits of using AspectJ?">
          <para>What are the benefits of using AspectJ?</para>
        </question>
        <answer>
          <para>AspectJ can be used to improve the modularity of software
            systems.
          </para>
          <para> Using ordinary Java, it can be difficult to modularize design
          concerns such as
          </para>
          <itemizedlist>
            <listitem><para>system-wide error-handling</para></listitem>
            <listitem><para>contract enforcement</para></listitem>
            <listitem><para>distribution concerns</para></listitem>
            <listitem><para>feature variations</para></listitem>
            <listitem><para>context-sensitive behavior</para></listitem>
            <listitem><para>persistence</para></listitem>
            <listitem><para>testing</para></listitem>
          </itemizedlist>
          <para>The code for these concerns tends to be spread out across the
            system. Because these concerns won't stay inside of any one module
            boundary, we say that they <emphasis>crosscut</emphasis> the
            system's modularity.
          </para>
          <para>AspectJ adds constructs to Java that enable the modular
            implementation of crosscutting concerns. This ability is
            particularly valuable because crosscutting concerns tend to be both
            complex and poorly localized, making them hard to deal with.
          </para>
          <!--
          <para>Initial studies have shown code size reductions of up to 40%
            and programmer productivity gains of 20%-40%. These studies were in
            an earlier version of the language and only for small sample sizes.
            So while the results are encouraging, they aren't conclusive. We
            intend to run a new set of studies once the current phase of
            language development stabilizes.</para>
-->
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:compability"
            xreflabel="Q:Can AspectJ work with any Java program?">
          <para>Can AspectJ work with any Java program?</para>
        </question>
        <answer>
          <para>AspectJ has been designed as a <emphasis>compatible</emphasis>
          extension to Java. By compatible, we mean
          </para>
          <informaltable frame="none">
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry align="right">
                    <emphasis>upward compatible</emphasis>
                  </entry>
                  <entry>All legal Java programs are legal AspectJ
                    programs.
                  </entry>
                </row>
                <row>
                  <entry align="right">
                    <emphasis>platform
                    compatible
                    </emphasis>
                  </entry>
                  <entry>All legal AspectJ programs run on standard Java
                    virtual machines.
                  </entry>
                </row>
                <row>
                  <entry align="right">
                    <emphasis>tool
                    compatible
                    </emphasis>
                  </entry>
                  <entry>Existing tools can be extended to work with
                    AspectJ.
                  </entry>
                </row>
                <row>
                  <entry align="right">
                    <emphasis>programmer compatible</emphasis>
                  </entry>
                  <entry>Programming in AspectJ feels natural to Java
                    programmers.
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
          <para>The AspectJ tools run on any Java 2 Platform compatible
            platform.  The AspectJ compiler produces classes that run
            on any Java 1.1 (or later) compatible platform.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:license" xreflabel="Q:How is AspectJ licensed?">
          <para>How is AspectJ licensed?</para>
        </question>
        <answer>
          <para>Since AspectJ 1.5.2, source code and documentation is available under the
            <ulink url="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License 1.0</ulink>.
          </para>
          <para>AspectJ 1.1 through 1.5.1 source code and documentation is available under the
            <ulink url="http://eclipse.org/legal/cpl-v10.html">Common Public License 1.0</ulink>.
          </para>
          <para>The AspectJ 1.0 tools are open-source software available under the
            <ulink url="http://www.opensource.org/licenses/mozilla1.1">Mozilla Public License 1.1</ulink>.
            That documentation is available under a separate license
            that precludes for-profit or commercial
              redistribution.  
          </para>
          <para>The runtime jar aspectjrt.jar and its distribution are also covered by the 
          <ulink url="http://www.eclipse.org/org/documents/epl-v10.php">Eclipse Public License</ulink>.
          </para>
          <para>For answers to common licensing questions, see the 
          <ulink url="http://www.eclipse.org/legal/eplfaq.php">Eclipse Public License FAQ</ulink>.
          </para>
          <para>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:project" xreflabel="Q:What is the AspectJ Project?">
          <para>What is the AspectJ Project?</para>
        </question>
        <answer>
          <para>AspectJ is based on over ten years of research at
            <ulink url="http://www.parc.xerox.com">
              Xerox Palo Alto Research Center
            </ulink> 
	as funded by Xerox, a U.S. Government grant (NISTATP), and a
            DARPA contract.
          </para>
          <para>It has evolved through open-source releases 
          to a strong user community and now operates as an
          open source project at 
           <ulink url="http://eclipse.org/aspectj">
                       http://eclipse.org/aspectj</ulink>
            The AspectJ team works closely with the community
            to ensure AspectJ continues to evolve as an effective 
            aspect-oriented programming language and tool set.
          </para>
          <para>
            The latest release is 1.2 <!-- XXX todo Update me! --> 
	        which can be downloaded from the 
             <ulink url="http://eclipse.org/aspectj">AspectJ project page</ulink>,
             including sources as described
             <xref linkend="q:buildingsource"/>.
             Development is focused on supporting applications, 
	         improving quality and performance, 
             enhancing integration with IDE's,
             and building the next generations of the language.
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="quickstart" xreflabel="Quick Start">
      <title>Quick Start</title>
      <qandaentry>
        <question id="q:requirements"
            xreflabel="Q:What Java versions does AspectJ require and support?">
          <para>
            What Java versions does AspectJ require and support?
          </para>
        </question>
        <answer>
          <para>
          The AspectJ compiler produces programs for any released version of the 
          Java platform (jdk1.1 and later).  When running, your program classes must
	      be able to reach classes in the
          small (&lt; 100K) runtime library (aspectjrt.jar) from the distribution.
          The tools themselves require J2SE 1.3 or later to run,
          but the compiler can produce classes for any 1.1-compliant
          version of the Java platform.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:install"
            xreflabel="Q:How do I download and install AspectJ?">
          <para>How do I download and install AspectJ?</para>
        </question>
        <answer>
          <para>From AspectJ's
            <ulink url="http://eclipse.org/aspectj">web page
            </ulink>, download the AspectJ distribution.
            The <literal>jar</literal> file is installed by executing
          </para>
          <programlisting>
            java -jar <emphasis>jar file name</emphasis>
          </programlisting>
          <para>Do <emphasis role="bold">not</emphasis> try to extract the
            <literal>jar</literal> file contents and then attempt to execute
            <literal>java org.aspectj.tools.Main</literal>. (A
            <classname>NoClassDefFoundError</classname> exception will be
            thrown.) The AspectJ distribution is not designed to be installed
            this way. Use the <literal>java -jar</literal> form shown above.
          </para>
          <para>To uninstall, remove the files the installer wrote in your 
            file system.  In most cases, you can delete the top-level install
	        directory (and all contained files), after you remove any
	        new or updated files you want to keep. On Windows, no
            registry settings were added or changed, so nothing needs to be
            undone.  Do not install over prior versions, which might have 
            different files.  Delete the prior version first.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:startUsingAJ"
            xreflabel="Q: How should I start using AspectJ?">
          <para>How should I start using AspectJ?</para>
        </question>
        <answer>
          <para>Many users adopt AspectJ in stages, first using it
        to understand and validate their systems (relying on it only in
        development) and then using it to implement crosscutting concerns
        in production systems.  AspectJ has been designed to make each
        step discrete and beneficial.
          </para>
          <para>
            In order of increasing reliance, you may use AspectJ:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold"> In the development
                    process
                </emphasis> Use AspectJ to trace or log
                  interesting information. You can do this by adding 
                  simple AspectJ code that performs logging or tracing. 
                  This kind of addition may be removed ("unplugged") for
                  the final build since it does not implement a design
                  requirement; the functionality of the system is unaffected by
                  the aspect.
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold">As an ancillary part of your
                    system
                </emphasis> Use AspectJ to more completely and
                    accurately test the system.
                  Add sophisticated code that can check contracts,
                  provide debugging support, or implement test strategies. 
                  Like pure development aspects, this code may also be 
                  unplugged from production builds. However, the same code
                  can often be helpful in diagnosing failures in deployed 
                  production systems, so you may design the functionality
                  to be deployed but disabled, and enable it when debugging.
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold">As an essential part of your
                    system
                </emphasis> Use AspectJ to modularize
                  crosscutting concerns in your system by design. 
                  This uses AspectJ to implement logic integral to a system
                  and is delivered in production builds.
              </para>
            </listitem>
          </itemizedlist>
          <para>This adoption sequence works well in practice and has been
          followed by many projects.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:integrateWithDevTools"
            xreflabel="Q: How well does AspectJ integrate with existing Java development tools?">
          <para>How does AspectJ integrate with existing Java development
            tools?
          </para>
        </question>
        <answer>
          <para>AspectJ products are designed to make it easy to integrate
          AspectJ into an existing development process.  
          Each release includes 
          Ant tasks for building programs,
          the AspectJ Development Environment (AJDE) for writing
          aspects inside popular IDE's,  and
          command-line tools for compiling and documenting Java and AspectJ code.
          </para>
          <!-- ok to order for style, not priority? -->
          <para>AspectJ provides replacements for standard Java tools:
            <itemizedlist>
              <listitem>
                <para><literal>ajc</literal>, the AspectJ compiler,
                  runs on any Java 2 compatible platform, and produces classes
                  that run on any Java 1.1 (or later) compatible platform.
                </para>
              </listitem>
              <listitem>
                <para><literal>ajdoc</literal> produces API documentation like
                javadoc, with additional crosscutting links.  For example,
                it shows advice affecting
                a particular method or all code affected by a given aspect.
                At present, <literal>ajdoc</literal> is only supported in AspectJ 1.0.
                </para>
              </listitem>
              <!-- restore ajdb, ajdoc -->
            </itemizedlist>
          </para>
          <para>For debugging, AspectJ supports JSR-45, which provides a mechanism for 
          debugging .class files that have multiple source files.
          Debugger clients and VM's are beginning to support this;
          see Sun's J2SE 1.4.1 VM and jdb debugger
          and recent versions of JBuilder.
          </para>
          <para>The AspectJ Development Environment (AJDE)
           enables programmers to view and navigate the crosscutting structures
           in their programs, integrated with existing support in 
           popular Java IDE's for viewing and navigating object-oriented
           structures. For many programmers this provides a deeper understanding
           of how aspects work to modularize their concerns and permits them
           to extend some of their development practices without 
           having to abandon their existing tools.
          </para>
          <para>
            AJDE is a set of API's providing the basis for the following
            development tool integrations:
          </para>
          <itemizedlist>
            <listitem>
              <para>Eclipse (version 2.0)
                   in the Eclipse AspectJ Development Tools project
                    <ulink url="http://eclipse.org/ajdt">
                                http://eclipse.org/ajdt
                    </ulink>
              </para>
            </listitem>
            <listitem>
              <para>Emacs (GNU version 20.3) 
                    and XEmacs (version 21.1 on Unix and 21.4 on Windows), 
                   in the SourceForge AspectJ for Emacs project
                    <ulink url="http://aspectj4emacs.sourceforge.net">
                                http://aspectj4emacs.sourceforge.net
                    </ulink>
              </para>
            </listitem>
            <listitem>
              <para>JBuilder (versions 4 through 7) from Borland
                    in the SourceForge AspectJ for JBuilder project
                    <ulink url="http://aspectj4jbuildr.sourceforge.net">
                                http://aspectj4jbuildr.sourceforge.net
                    </ulink>
              </para>
            </listitem>
            <listitem>
              <para>Netbeans up to 3.4
                    (and Sun Microsystems' Forte for Java (versions 2 and 3), Sun/One)
                    in the SourceForge AspectJ for NetBeans project
                    <ulink url="http://aspectj4netbean.sourceforge.net">
                                http://aspectj4netbean.sourceforge.net
                    </ulink>
              </para>
            </listitem>
          </itemizedlist>
          <para>
            The common functionality of AJDE is also available in
            the stand-alone source code browser <literal>ajbrowser</literal>,
            included in the tools distribution.
          </para>
          <para>Finally, as mentioned above,
           AspectJ also supports building with Ant by providing
           task interfaces to the ajc and ajdoc tools.
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="typicalprograms" xreflabel="Typical AspectJ programs">
      <title>Typical AspectJ programs</title>
      <qandaentry>
        <question id="q:aspectsoptional"
            xreflabel="Q:Are aspects always optional or non-functional parts of a program?">
          <para>Are aspects always optional or non-functional parts of
            a program?
          </para>
        </question>
        <answer>
          <para>No. Although AspectJ can be used in a way that allows AspectJ
            code to be removed for the final build, aspect-oriented code is not
            <emphasis>always</emphasis> optional or non-functional. Consider
            what AOP really does: it makes the modules in a program correspond
            to modules in the design. In any given design, some modules are
            optional, and some are not.
          </para>
          <para>The examples directory included in the AspectJ distribution
            contains some examples of the use aspects that are not optional.
            Without aspects,
          </para>
          <informaltable frame="none">
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry align="right">
                    <emphasis role="strong">bean</emphasis>
                  </entry>
                  <entry>Point objects would not be JavaBeans.</entry>
                </row>
                <row>
                  <entry align="right">
                    <emphasis role="strong">introduction</emphasis>
                  </entry>
                  <entry>Point objects would not be cloneable, comparable or
                    serializable.
                  </entry>
                </row>
                <row>
                  <entry align="right">
                    <emphasis role="strong">spacewar</emphasis>
                  </entry>
                  <entry>Nothing would be displayed.</entry>
                </row>
                <row>
                  <entry align="right">
                    <emphasis role="strong">telecom</emphasis>
                  </entry>
                  <entry>No calls would be billed.</entry>
                </row>
              </tbody>
            </tgroup>
          </informaltable>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:developmentAndProductionAspects"
            xreflabel="Q:What is the difference between development and production aspects?">
          <para>
            What is the difference between development and production aspects?
          </para>
        </question>
        <answer>
          <para>
            Production aspects are delivered with the finished product,
	    while development aspects are used during the development process.
	    Often production aspects are also used during development.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:devAspects"
            xreflabel="Q:What are some common development aspects?">
          <para>
            What are some common development aspects?
          </para>
        </question>
        <answer>
          <para>Aspects for logging, tracing, debugging, profiling
	   or performance monitoring, or testing.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:prodAspects"
            xreflabel="Q:What are some common production aspects?">
          <para>
            What are some common production aspects?
          </para>
        </question>
        <answer>
          <para>
            Aspects for performance monitoring and diagnostic systems, 
	    display updating or notifications generally, security, 
	    context passing, and error handling.
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="concepts" xreflabel="Basic AOP and AspectJ Concepts">
      <title>Basic AOP and AspectJ Concepts</title>
      <qandaentry>
        <question id="q:crosscutting"
            xreflabel="Q:What are scattering, tangling, and crosscutting?">
          <para>What are scattering, tangling, and crosscutting?</para>
        </question>
        <answer>
          <para>
	      "Scattering" is when similar code is distributed throughout many 
          program modules.  This differs from a component being used by 
          many other components since
	      it involves the risk of misuse at each point and of inconsistencies
	      across all points.  Changes to the implementation may require
          finding and editing all affected code.
          </para>
          <para>"Tangling" is when two or more concerns are implemented in
	      the same body of code or component, making it more difficult to understand.
	      Changes to one implementation may cause unintended changes
	      to other tangled concerns.
          </para>
          <para>"Crosscutting" is how to characterize a concern than spans
	      multiple units of OO modularity - classes and objects.  Crosscutting
	      concerns resist modularization using normal OO constructs, but 
          aspect-oriented programs can modularize crosscutting concerns.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:joinpoints"
            xreflabel="Q: What are join points?">
          <para>What are join points?</para>
        </question>
        <answer>
          <para>Join points are well-defined points in the execution of a
            program. Not every execution point is a join point: only those
            points that can be used in a disciplined and principled manner are.
            So, in AspectJ, the execution of a method call is a join point, but
            "the execution of the expression at line 37 in file Foo.java" is
            not.
          </para>
          <para>The rationale for restricting join points is similar to the
            rationale for restricting access to memory (pointers) or
            restricting control flow expressions (<literal>goto</literal>) in
            Java: programs are easier to understand, maintain and extend
            without the full power of the feature.
          </para>
          <para>AspectJ join points include reading or writing a field; calling
            or executing an exception handler, method or constructor.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:pointcut"
            xreflabel="Q; What is a pointcut?">
          <para>
            What is a pointcut?
          </para>
        </question>
        <answer>
          <para>A pointcut picks out
            <link linkend="q:joinpoints">
              join points
            </link>. These join points are described by the pointcut
              declaration. Pointcuts can be defined in classes or in aspects,
              and can be named or be anonymous.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:advice"
            xreflabel="Q:What is advice?">
          <para>What is advice?</para>
        </question>
        <answer>
          <para>Advice is code that executes at each
	    <link linkend="q:joinpoints">join point</link> picked out by a
            <link linkend="q:pointcut">pointcut</link>. There are three
            kinds of advice: before advice, around advice and after advice. As
            their names suggest, before advice runs before the join point
            executes; around advice executes before and after the join point;
            and after advice executes after the join point. The power of
            advice comes from the advice being able to access values in the
            execution context of a pointcut.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:declarations"
            xreflabel="Q:What are inter-type declarations?">
          <para>What are inter-type declarations?</para>
        </question>
        <answer>
          <para>AspectJ enables you to declare members and supertypes of another class
	in an aspect, subject to Java's type-safety and access rules.  These are
	visible to other classes only if you declare them as accessible.  
        You can also declare compile-time errors and warnings based on pointcuts.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:whatisanaspect"
            xreflabel="Q:What is an aspect?">
          <para>What is an aspect?</para>
        </question>
        <answer>
          <para>Aspects are a new class-like language element that has been
            added to Java by AspectJ. Aspects are how developers encapsulate
            concerns that cut across classes, the natural unit of modularity in
            Java.
          </para>
          <para>Aspects are similar to classes because...
            <itemizedlist>
              <listitem><para>aspects have type</para></listitem>
              <listitem>
                <para>
                  aspects can extend classes and other aspects
                </para>
              </listitem>
              <listitem>
                <para>
                  aspects can be abstract or concrete
                </para>
              </listitem>
              <listitem>
                <para>
                  non-abstract aspects can be instantiated
                </para>
              </listitem>
              <listitem>
                <para>aspects can have static and non-static state and
                  behavior
                </para>
              </listitem>
              <listitem>
                <para>aspects can have fields, methods, and types
                  as members
                </para>
              </listitem>
              <listitem>
                <para>the members of non-privileged aspects follow the
                  same accessibility rules as those of classes
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>Aspects are different than classes because...
            <itemizedlist>
              <listitem>
                <para>aspects can additionally include as members pointcuts,
                  advice, and inter-type declarations;
                </para>
              </listitem>
              <listitem>
                <para>aspects can be qualified by specifying the
                  context in which the non-static state is available
                </para>
              </listitem>
              <listitem>
                <para>aspects can't be used interchangeably with
                  classes
                </para>
              </listitem>
              <listitem>
                <para>aspects don't have constructors or finalizers,
                  and they cannot be created with the new operator;
		  they are automatically available as needed.
                </para>
              </listitem>
              <listitem>
                <para>privileged aspects can access private members of
                  other types
                </para>
              </listitem>
            </itemizedlist>
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="whyaop" xreflabel="Why AOP?">
      <title>Why AOP?</title>
      <qandaentry>
        <question id="q:ccfromflaws"
            xreflabel="Q:Are crosscutting concerns induced by flaws?">
          <para>Are crosscutting concerns induced by flaws in parts of the
          system design, programming language, operating system, etc. Or is
          there something more fundamental going on?
          </para>
        </question>
        <answer>
          <para>AOP's fundamental assumption is that in any sufficiently
            complex system, there will inherently be some crosscutting
            concerns.
          </para>
          <para>So, while there are some cases where you could re-factor a
            system to make a concern no longer be crosscutting, the AOP idea
            is that there are many cases where that is not possible, or where
            doing so would damage the code in other ways.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:definingaspectspercc"
            xreflabel="Q:Does it really make sense to define aspects in terms of crosscutting?">
          <para>Does it really make sense to define aspects in terms of
          crosscutting?
          </para>
        </question>
        <answer>
          <para>Yes.</para>
          <para>The short summary is that it is right to define AOP in terms of
            crosscutting, because well-written AOP programs have clear
            crosscutting structure.  It would be a mistake to define AOP in
            terms of "cleaning up tangling and scattering", because that isn't
            particular to AOP, and past programming language innovations also
            do that, as will future developments.
          </para>
          <para>(Slides for a long talk on this topic were once available at
              http://www.cs.ubc.ca/~gregor/vinst-2-17-01.zip.)
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:domainspecific"
            xreflabel="Q:Is AOP restricted to domain-specific applications?">
          <para>Is AOP restricted to domain-specific
            applications?
          </para>
        </question>
        <answer>
          <para>No. Some implementations of AOP are domain-specific, but
            AspectJ was specifically designed to be general-purpose.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:whyaopifinterceptors"
            xreflabel="Q:Why do I need AOP if I can use interceptors?">
          <para>Why do I need AOP if I can use interceptors
                (or JVMPI or ref
            lection)?
          </para>
        </question>
        <answer>
          <para>There are many mechanisms people use now to implement
          some crosscutting concerns.  But they don't have a way to express
          the actual structure of the program so you (and your tools)
	  can reason about it.  Using a language enables you to express the 
          crosscutting in first-class constructs.  You can not only avoid the 
          maintenance problems and structural requirements of some other 
          mechanisms, but also combine forms of crosscutting so that all
	  the mechanisms for a particular concern are one piece of code.
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="related" xreflabel="Related Technology">
      <title>Related Technology</title>
      <qandaentry>
        <question id="q:comparetonewforms"
            xreflabel="Q:How does AspectJ compare to other new forms of programming?">
          <para>
            How does AspectJ compare to other new forms of programming?
          </para>
        </question>
        <answer>
          <para>There are many recent proposals for programming languages that
            provide control over crosscutting concerns. Aspect-oriented
            programming is an overall framework into which many of these
            approaches fit. AspectJ is one particular instance of AOP,
            distinguished by the fact that it was designed from the ground up
            to be compatible with Java.
          </para>
          <para>For more alternatives for aspect-oriented programming, see 
            <ulink url="http://aosd.net">http://aosd.net</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:compartoreflection"
            xreflabel="Q:How do you compare the features of AspectJ with reflective systems?">
          <para>How do you compare the features of AspectJ with
            reflective systems?
          </para>
        </question>
        <answer>
          <para>Reflective and aspect-oriented languages have an important
            similarity: both provide programming support for dealing with
            crosscutting concerns. In this sense reflective systems proved 
            that independent programming of crosscutting concerns is
            possible.
          </para>
          <para>But the control that reflection provides tends to be low-level
            and extremely powerful. In contrast, AspectJ provides more
            carefully controlled power, drawing on the rules learned from
            object-oriented development to encourage a clean and understandable
            program structure.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:comparetomixin"
            xreflabel="Q:How do AspectJ features compare with those of mixin-based inheritance?">
          <para>How do AspectJ features compare with those of mixin-based
            inheritance?
          </para>
        </question>
        <answer>
          <para>Some features of AspectJ, such as introduction, are related to
            <emphasis>mixin-based inheritance</emphasis>. But, in order to
            support crosscutting, a core goal for AspectJ, AspectJ goes beyond
            mixin-based inheritance.
          </para>
          <para>Firstly, an aspect imposes behavior on a class, rather than a
            class requesting behavior from an aspect. An aspect can modify a
            class without needing to edit that class. This property is
            sometimes called <emphasis>reverse inheritance</emphasis>.
          </para>
          <para>Secondly, a single aspect can affect multiple classes in
            different ways. A single paint aspect can add different paint
            methods to all the classes that know how to paint, unlike mixin
            classes.
          </para>
          <para>
So mixin-based inheritance doesn't have the reverse inheritance
property, and mixins affect every class that mixes them in the same.
If I want to do something like SubjectObserverProtocol, I need two
mixins, SubjectPartofSubjectObserverProtocol and ObserverPartof...
In AspectJ, both halves of the protocol can be captured in a single
aspect.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:dynamicaop"
            xreflabel="Q:How does AspectJ compare with more dynamic AOP?">
          <para>How does AspectJ compare with more dynamic AOP?
          </para>
        </question>
        <answer>
          <para>
          Some AOP techniques are presented as "dynamic" because the weaving 
          occurs when classes are loaded, because aspects can be configured 
          in a separate XML file before launch, or because some advice
          depends on runtime reflection.  They are said to be more flexible
          than AspectJ.
          </para>
          <para>
          This is a misconception.  First, the AspectJ 1.1 weaver has always 
          supported weaving at compile-time or class-load-time.  Weaving at
          compile-time reduces application launch and running time, and it helps
          IDE's offer support for tracking down weaving errors and understanding
          the impact of aspects on a system.
          On the other hand, weaving at load-time simplifies build and deployment.
          Before AspectJ 1.2, the user had to write a class loader that used the 
          weaver API to weave at load time; since 1.2, AspectJ comes with a 
          command-line launcher to support weaving at class-load-time without 
          any other changes to a build configuration.  In AspectJ 5, we expect
		  to get a similar level of support as AspectWerkz, and to exploit
		  the class bytecode weaving hook available in Java 5 VM's.
          </para>
          <para>
          Second, AspectJ programs, like Java programs generally, can be
          written to support any level of XML configuration or to depend on
          runtime reflection.  There are some benefits to using AspectJ;
          e.g., the proceed() form within around advice simplifies a lot of 
          the work that otherwise would go into writing a generalized 
          interceptor, without introducing many of the runtime errors that can 
          result from interceptors.  
          For AspectJ examples of configurable or reflection-dependent programs,
          see the sample code linked off the AspectJ documentation page
          or the examples discussed on the mailing list, e.g.,
          <ulink url="http://dev.eclipse.org/mhonarc/lists/aspectj-users/msg02151.html">
			Incremental and runtime weaving support?</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:aopandxp"
            xreflabel="Q:What is the relationship between AOP and 
        XP (extreme programming AKA agile methods)?">
          <para>What is the relationship between AOP and 
        XP (extreme programming AKA agile methods)?
          </para>
        </question>
        <answer>
          <para>From a question on the user list:
            <programlisting>
> Anyone know the connections between AOP and Extreme Programming?
> I am really confused. It seems AOP is a programming paradigm, which
> is the next level of abstraction of OOP. Extreme Programming, however,
> this is a lightweight software development process. One of the common
> motivations of AOP and XP is designed to adopt to the requirement
> changes, so that it can save the cost of software development.
            </programlisting>
          </para>
          <para>
            This is Raymond Lee's answer:
          </para>
          <para>
        You're not really that confused.  AOP and XP are orthogonal concepts,
        although AOP can be used to help accomplish XP goals.
        One of the goals of XP is to respond to changing requirements.
        Another is to reduce the overall cost of development.  These are
        not necessarily the same thing.
          </para>
          <para>
        One of the principles of XP that contribute to meeting those goals
        is to maintain clean, simple designs.  One of the criteria for clean,
        simple designs is to factor out duplication from the code.  Benefits
        of removing duplication include the code being easier to understand,
        better modularity of the design, lower costs of code changes, less
        chance of conflicting changes when practicing collective code
        ownership, etc.
          </para>
          <para>
        Different types of duplication lend themselves to being addressed by
        different design paradigms and language features.  Duplicate snippets
        of code can be factored out into methods.  Duplicate methods can be
        factored out to common classes, or pushed up to base classes.
        Duplicate patterns of methods and their use can be factored out to
        mechanisms of classes and methods (i.e. instantiations of design
        patterns).
          </para>
          <para>
        AOP addresses a type of duplication that is very difficult to handle
        in the other common paradigms, namely cross-cutting concerns.  By
        factoring out duplicate cross-cutting code into aspects, the target
        code becomes simpler and cleaner, and the cross-cutting code becomes
        more centralized and modular.
          </para>
          <para>
        So, AOP as a paradigm, and the associated tools, gives an XPer, or
        anyone wanting to remove duplication from the code base, a powerful
        way to remove a form of duplication not easily addressed until now.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:aspectjandcsharp"
            xreflabel="Q:Will you support C#?">
          <para>Will you support C#?</para>
        </question>
        <answer>
          <para>Not at this time. Although the resemblances between C# and Java
            means it would probably be a fairly straightforward matter to take
            the AspectJ language design and produce AspectC#, our current focus
            is only on supporting effective uses of AspectJ.
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="adoption" xreflabel="Deciding to adopt AspectJ">
      <title>Deciding to adopt AspectJ</title>
      <qandaentry>
        <question id="q:productplans"
            xreflabel="Q:Is it safe to use AspectJ in my product plans??">
          <para>
            Is it safe to use AspectJ in my product plans?
          </para>
        </question>
        <answer>
          <para>You may use AspectJ in your product or project with little
            risk. Several factors play a role in reducing the risk of adopting
            this new technology:
            <itemizedlist>
              <listitem>
                <para>AspectJ is an <emphasis>addition</emphasis> to
                  Java, and can be introduced into a project 
                  in a way that limits risk. 
                  See <xref linkend="q:startUsingAJ"/> for
                  some suggestions on how to do this.
                </para>
              </listitem>
              <listitem>
                <para>The AspectJ compiler accepts standard Java as
                  input and produces standard Java bytecode as output. 
                  In 1.0, an optional mode produces standard Java source code 
                  which may then be compiled with any compliant Java compiler
                  (e.g. Sun's <literal>javac</literal> compiler 
                  or IBM's <literal>jikes</literal> compiler).
                  In 1.1, an optional mode accepts standard Java bytecode 
                  from any compliant Java compiler 
                  and weaves in the aspects to produce new bytecode.
                </para>
              </listitem>
              <listitem>
                <para>AspectJ is available under a non-proprietary, open source license,
                 either the 
                  <ulink url="http://www.opensource.org/licenses/mozilla1.1">
                            Mozilla Public License 1.1</ulink>
                  for 1.0 or the
                  <ulink url="http://eclipse.org/legal/cpl-v10.html">
                   Common Public License 1.0</ulink> for 1.1.
                  AspectJ will continue to evolve and be available, regardless
                  of the fate of any particular organization involved with
                  AspectJ.
                </para>
              </listitem>
              <listitem>
                <para>Removing AspectJ from your program is not
                  difficult, although you will lose the flexibility and
                  economy that AspectJ provided.
                </para>
              </listitem>
              <listitem>
                <para>A number of significant open-source projects and industry 
                    products use AspectJ successfully.  One list is kept on
                    <ulink url="http://www.aosd.net/wiki/index.php?title=FAQ">
                        the AOSD FAQ</ulink>, and more appear on the mailing
                    lists (search for, e.g., "AspectJ in real world", as
                    described in <xref linkend="q:searchingsite"/>).
                </para>
              </listitem>
            </itemizedlist>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:effectonsize"
            xreflabel="Q:What is the effect of using AspectJ on the source code size of programs?">
          <para>What is the effect of using AspectJ on the source code
            size of programs?
          </para>
        </question>
        <answer>
          <para>Using aspects reduces, as a side effect, the number of source
            lines in a program. However, the major benefit of using aspects
            comes from <emphasis>improving</emphasis> the modularity of a
            program, not because the program is smaller. Aspects gather into a
            module concerns that would otherwise be scattered across or
            duplicated in multiple classes.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:effectonperformance"
            xreflabel="Q:Does AspectJ add any performance overhead?">
          <para>
            Does AspectJ add any performance overhead?
          </para>
        </question>
        <answer>
          <para>The issue of performance overhead is an important one. It is
            also quite subtle, since knowing what to measure is at least as
            important as knowing how to measure it, and neither is always
            apparent.
          </para>
          <para>We aim for the performance of our implementation of AspectJ to 
          be on par with the same functionality hand-coded in Java.  Anything
          significantly less should be considered a bug.
          </para>
          <para>There is currently no benchmark suite for AOP languages in
            general or for AspectJ in particular. It is probably too early to
            develop such a suite because AspectJ needs more maturation of the
            language and the coding styles first. Coding styles really drive
            the development of the benchmark suites since they suggest what is
            important to measure.
          </para>
          <para>Though we cannot show it without a benchmark suite, we believe
          	that code generated by AspectJ has negligible performance overhead.
            Inter-type member and parent introductions should have very little
            overhead, and advice should only have some indirection which 
            could be optimized away by modern VM's.
          </para>
          <para>The <literal>ajc</literal> compiler will use static typing information 
            to only insert the advice and dynamic pointcut tests that are absolutely necessary.  
            Unless you use 'thisJoinPoint' or 'if', the main dynamic checks will be 
            'instanceof' checks which are generally quite fast.  
            These checks will only be inserted when they can not be inferred from 
            the static type information.
          </para>
          <para>When measuring performance, write AspectJ code
            fragments and compare them to the performance of the
            corresponding code written without AspectJ. For example, don't
            compare a method with before/after advice that grabs a lock to just
            the method. That would be comparing apples and oranges. Also be
            sure to watch out for JIT effects that come from empty method
            bodies and the like. Our experience is that they can be quite
            misleading in understanding what you've measured.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:modularityviolations"
            xreflabel="Q:I've heard that AspectJ leads to modularity violations.  Does it?">
          <para>
            I've heard that AspectJ leads to modularity violations.  Does it?
          </para>
        </question>
        <answer>
          <para>
            Well I haven't yet seen a language in which you can't write bad code!
          </para>
          <para>
        But seriously, most AspectJ users find that just like when they learned 
        OO, it takes a while to really get the hang of it.  They tend to start 
        in the usual way, by copying canonical examples and experimenting with 
        variations on them.
          </para>
          <para>
        But users also find that rather than being dangerous, AspectJ helps them 
        write code that is more clear and has better encapsulation -- once they 
        understand the kind of modularity AspectJ supports.  There are several 
        good papers that talk about this (see below), but here's a basic point 
        to keep in mind: when properly used, AspectJ makes it possible program 
        in a modular way, something that would otherwise be spread throughout 
        the code. Consider the following code, adapted from the AspectJ tutorial:
          </para>
          <programlisting>
aspect PublicErrorLogging {
    Log log = new Log();

    pointcut publicInterface(Object o):
        call(public * com.xerox.*.*(..)) &amp;&amp; target(o);

    after(Object o) throwing (Error e): publicInterface(o) {
        log.write(o, e);
    }
}
          </programlisting>
          <para>
        The effect of this code is to ensure that whenever any public method of 
        an interface or class in the <literal>com.xerox</literal> package 
        throws an error, that error is logged before being thrown to its caller.
          </para>
          <para>
        Of course in the alternative implementation a large number of methods 
        have a try/catch around their body.
          </para>
          <para>
        The AspectJ implementation of this crosscutting concern is clearly 
        modular, whereas the other implementation is not.  As a result, if you 
        want to change it, its easier in the AspectJ implementation.  For 
        example, if you also want to pass the name of the method, or its 
        arguments to <literal>log.write</literal>, you only have to edit 
        one place in the AspectJ code.
          </para>
          <para>
        This is just a short example, but I hope it shows how what happens 
        with AOP and AspectJ is that the usual benefits of modularity are 
        achieved for crosscutting concerns, and that leads to better code, 
        not more dangerous code.
          </para>
          <para>
        One paper someone else just reminded me of that talks some more 
        about this is:
            <ulink url="http://www.cs.ubc.ca/~kdvolder/Workshops/OOPSLA2001/submissions/12-nordberg.pdf">
              http://www.cs.ubc.ca/~kdvolder/Workshops/OOPSLA2001/submissions/12-nordberg.pdf
            </ulink>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:encapsulation"
            xreflabel="Q:Why does AspectJ permit aspects to access and add members of another type?">
          <para>
            Why does AspectJ permit aspects to access and add members of another type?  
            Isn't that violating OO encapsulation?
          </para>
        </question>
        <answer>
          <para>In the spirit of Smalltalk, we have decided to give more power
            to the language in order to let the user community experiment and
            discover what is right. To date this has proven to be a successful
            strategy because it has permitted the construction of many useful
            aspects that crosscut the internal state of an object, and as such
            need access the its private members. However, we are not
            discounting that some sort of restrictions are useful, rather, we
            are seeking input from the community in order to decide on what
            these restrictions should be.
          </para>
          <para>
            In that light, our position on encapsulation is :
          </para>
          <itemizedlist>
            <listitem><para>we respect Java's visibility rules</para></listitem>
            <listitem><para>we also provide open-classes, a mature OO technology</para></listitem>
            <listitem><para>we provide "privileged" access if you really need it.</para></listitem>
          </itemizedlist>
          <para>
          Introducing parents or members to classes is a well-studied OO technique
          known as open classes.
          </para>
          <para>
          Open classes have been used in many languages prior to AspectJ, 
          including CLOS, Python, Smalltalk, Objective-C, and others.  
          Building from Java, introduction in AspectJ provides better 
          name hygiene and access control than prior languages.  
          Introduced code obeys all of Java's normal accessibility rules 
          for its lexical location in the aspect that it is introduced from.  
          Such code can not even see, much less access, private members of 
          the class it is introduced into. Further, introductions can be
          declared private to the aspect, so they are not visible to
          other clients of the class.
          </para>
          <para>
          Privileged aspects do permit access to private members of another
          class.  They are a response to the very few cases where developers 
          genuinely need such access (typically for testing purposes where it
          access is necessary), but it would be more risky to open access by
          putting the aspect in the same package, adding test code, or changing
          access in the target class.  We recommend using privileged aspects 
          only as necessary, and believe that marking them "privileged" makes 
          any potential misuse apparent.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:aspectjandj2ee"
            xreflabel="Q:Can I use AspectJ with J2EE?">
          <para>Can I use AspectJ with J2EE?</para>
        </question>
        <answer>
          <para>
            Consider the component types in J2EE:
          </para>
          <itemizedlist>
            <listitem>
              <para>
                Servlet: AspectJ works well within servlets
              </para>
            </listitem>
            <listitem>
              <para>
	JSP: It is possible to use AspectJ to affect code in JSPs by precompiling
	them into Java sources and compiling these with ajc. This can be used, e.g., to 
	customize displays by turning on and off custom JSP taglibs. The mapping from a
	given jsp source to java package and class name is not standardized, which means
	doing this imposes dependencies on specific container versions.
              </para>
            </listitem>
            <listitem>
              <para>
	EJB: AspectJ supports a wide variety of aspects for EJBs. It can be used for 
	logging, tracing, debugging, error handling by layers, correlated method-level
	interception (e.g., chargebacks), metering, fine-grained transactions, etc.
	Indeed, it can be used to enforce adherence to coding restrictions within an
	EJB (e.g., not using java.io, creating a class loader, or listening on 
	sockets) using <literal>declare error</literal>.
              </para>
            </listitem>
          </itemizedlist>
          <para>
	The basic limitations are that there is no built-in support for writing J2EE
	analogs for AspectJ extensions to Java, like distributed aspects, distributed 
	cflow, or managing state between invocations. These don't prevent one from using
	AspectJ to do useful intra-container implementation, nor need they prevent one 
	from building distributed support, state management, and inter-component 
	implementations that leverage AspectJ. It just takes some work. In more detail:
          </para>
          <para>
	All AspectJ implementations may define "code the implementation controls".
        The AspectJ 1.0 implementation defines this as the files passed to the compiler
        (AspectJ 1.1 will also support bytecode weaving).
          </para>
          <para>
	Some advice on EJB operations will generate methods that confuse ejb compilers.
	To avoid this problem, you can use the -XaddSafePrefix flag when compiling with ajc.
          </para>
          <para>
	EJB components may be invoked remotely, and containers may passivate and 
	pool EJB's.  Servlets have similar limitations, and in both cases the
	lifespan of the defining class loader is implementation-dependent 
	(though it must span the operation of a particular request).
          </para>
          <para>
	Being limited by lifecycle and namespace, the AspectJ 1.0 implementation 
        supports aspects that operate through non-remote invocations during the lifetime 
        of the namespace for a particular 
	deployment unit compiled in its entirety by the ajc compiler.
	This means AspectJ supports common aspects only within a single local runtime
	namespace (usually implemented as a class loader hierarchy).
          </para>
          <para>
	Further, AspectJ recognizes language-level join points (object initialization, 
	method calls, etc.), not their EJB analogs (ejb find or create methods...).
	These lead to the following consequences:
          </para>
          <itemizedlist>
            <listitem>
              <para>
	Issingleton aspects (the default) are limited to the lifetime of
	the defining class loader, which in some implementations may not span
	multiple invocations of the same application or EJB component.
              </para>
            </listitem>
            <listitem>
              <para>
	EJB lifecycles are different from object lifecycles, so perthis
	and pertarget aspects will make little sense.  They do not work
        in the current implementation, which uses synchronized methods
        to ensure a correct association in threaded environments 
        (EJB's may not have synchronized methods).
              </para>
            </listitem>
            <listitem>
              <para>
	Percflow or percflowbelow aspects are restricted to a chain of
	non-remote invocations.  While EJB 2.0 permits declaring an interface
	local, this information is not available to the AspectJ compiler today.
        For same reasons as stated above fore perthis, these will not work even 
        in the EJB container.
              </para>
            </listitem>
            <listitem>
              <para>
	Evaluation of cflow or cflowbelow pointcuts will be valid only
	with respect to a chain of non-remote invocations.
              </para>
            </listitem>
          </itemizedlist>
          <para>
            In addition, any AspectJ code should respect EJB operations:
          </para>
          <itemizedlist>
            <listitem>
              <para>
	The EJB container accesses EJB component fields directly, i.e.,
	in code outside the control of the compiler.  There is no join point for
	these accesses, and hence no way to write a pointcut to advise that access.
              </para>
            </listitem>
            <listitem>
              <para>
	The EJB container may pool EJB components, so any initialization
	join points may run once per component constructed, not once per
	component initialized for purposes of a client call.
              </para>
            </listitem>
            <listitem>
              <para>
	The EJB container is permitted to change class loaders, even
	between invocations of a particular EJB component (by passivating and
	activating with a new class loader).  In this case, instances of singleton 
	aspects will not operate over multiple invocations of the component, or that 
	static initialization join point recur for a given class as it is re-loaded. 
	This behavior depends on the container implementation.
              </para>
            </listitem>
          </itemizedlist>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:aspectjandgj"
            xreflabel="Q:Can I use AspectJ with Generic Java?">
          <para>Can I use AspectJ with Generic Java?</para>
        </question>
        <answer>
        	<para>We plan to support Generics when Java 1.5 is available.
        	</para>
          <para>But at this time, unfortunately not. The two compilers are just not
            at all compatible. In an ideal world, there would be a wonderful
            Open Source extensible compiler framework for Java that both GJ and
            AspectJ would be built on top of, and they would seamlessly
            interoperate along with all other extensions to Java that you might
            be interested in, but that's not the case (yet?).
          </para>
          <para>However, on 09 October 2000, the Java Community Process
            approved a proposal to add generic types to Java that is largely
            based on GJ (JSR 14).  A draft specification was submitted for
            public review, which closed on 01 August 2001, and a
              prototype implementation has been released by Sun.
          </para>
          <para>We are committed to moving very rapidly to add support for
            generic types in AspectJ when generic types become part of the Java
            language specification.  Everyone on the AspectJ team is looking
            forward to this, because we too would really like to be able to
            write code that includes both aspects and generic types.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:aspectjandj2me"
            xreflabel="Q:Can I use AspectJ with J2ME?">
          <para>Can I use AspectJ with J2ME?</para>
        </question>
        <answer>
        	<para>The J2ME platform has several different components.
        	The diagram below shows how the different profiles
        	build on top of the two configurations CDC (Connected Device
        	Configuration) and CLDC (Connected Limited Device Configuration):
        		<programlisting>
    --------------
    |  Personal  |
    --------------      --------
    | Foundation |      | MIDP |
  ------------------  ------------------
  |      CDC       |  |      CLDC      |
------------------------------------------
|                 Java                   |
------------------------------------------  
                </programlisting>
            Which configuration you have dictates the restrictions when
            running AspectJ compiled programs.    
        	</para>
        	<para>
        	If you're running with a profile which sits on top of CDC then
        	there are not, as far as we are aware, any restrictions when 
        	running AspectJ compiled code on this flavour of J2ME. 
        	</para>
        	<para>
        	If you're running with a profile sitting on top of CLDC 1.1
        	you are currently unable to use the <literal>thisJoinPoint,
        	thisJoinPointStaticPart</literal> and <literal>
        	thisEnclosingJoinPointStaticPart</literal> variables, the 
        	<literal>cflow</literal> and <literal>cflowbelow</literal> 
        	pointcuts and the <literal>percflow</literal> and <literal>
        	percflowbelow</literal> perClauses.
        	</para>
        	<para>
        	Finally, if you're running with a profile which sits on top
        	of CLDC 1.0 you have all the restrictions of CLDC 1.1. There may
        	be further restrictions due to the lack of types corresponding
        	to the primitive types (e.g. Integer.TYPE), however, at the
        	time of writing we have been unable to do any extensive testing
        	on this.
        </para>
        <para>
        Note that the aspectj runtime jar is now (as of AspectJ5) quite
        large but only a small subset is required for executing code
        in J2ME environments.  We plan to ship a second aspectjrt.jar
        built for the J2ME environment at some point.
        </para>
        <para>
        For more discussion and to raise any issues you have with
        AspectJ and J2ME, refer to
        	<ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=92933">
               bugzilla entry 92933</ulink>.        	
        	</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:aopinjava"
            xreflabel="Q: Are you working to put AOP into Java?">
          <para> Are you working to put AOP into Java?  
	   It seems that every AOP toolset currently uses proprietary mechanisms 
	   to describe point-cuts, etc.
          </para>
        </question>
        <answer>
          <para>
	We are working on standardization, but it's 
	a question of timing/ripeness (imagine going from thousands of users 
	to millions).  (See <xref linkend="q:standardization"/>.) We believe 
	AspectJ addresses this question in the best way possible now:
            <itemizedlist>
              <listitem>
                <para>
	It's open-source.  Rather than being proprietary or controlled by a 
	vendor, it's available for anybody to use and build upon, forever.
                </para>
              </listitem>
              <listitem>
                <para>
	AspectJ is not a set of mechanisms, it's a language.  It is currently 
	implemented using certain techniques, but there's nothing that prevents 
	it from being implemented with other techniques.  That means users can 
	adopt the language with confidence that implementations will get better.
                </para>
              </listitem>
              <listitem>
                <para>
	There is no engineering need to change Java.  The AspectJ language uses 
	the join point model already in Java, so there is no need to extend the 
	programming model.  Our implementation produces valid Java bytecode, which 
	runs in any compliant J2SE VM and supports standard debuggers for those VM's 
	that support JSR-45 (debugging support for multi-language/multi-file sources).  
	This is a huge benefit to Sun since Sun must be extremely cautious 
	about extensions to the language or VM; before adopting AOP, Sun should 
	demand the kind of actual-proof that AspectJ implementations offer.
                </para>
              </listitem>
              <listitem>
                <para>
	On the issue of "proprietary mechanisms to describe pointcuts, etc.":   Any AOP 
	has to have some language to describe pointcuts and the like ("pointcuts" 
	of course being the AspectJ term).  Users would like to have one language 
	(to avoid having to learn or transform between many languages) and the 
	choice of multiple implementations (tailored for a configuration, subject 
	to competitive pressure, etc.).  That's what AspectJ offers.
                </para>
              </listitem>
              <listitem>
                <para>
	That said, we believe the AspectJ extensions to Java could form the basis 
	for bringing AOP to Java; when that happens, there will be engineering 
	opportunities to make the implementation and tool support better.
                </para>
              </listitem>
            </itemizedlist>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:support"
            xreflabel="Q: What kind of support is available?">
          <para>What kind of support is available?</para>
        </question>
        <answer>
          <para>
          	The mailing lists provide the primary support for everyone
          	in the community
          	(See <xref linkend="q:mailingLists"/>).
            To request commercial support, tutorials, or presentations,
            use the developer mailing list,
            <literal>aspectj-dev@eclipse.org</literal>.
          </para>
          <para>
          To find out about known issues, see the
          <ulink url="progguide/implementation.html">
          AspectJ Programming Guide Appendix, "Implementation Notes"</ulink>
          and the AspectJ bugs in the database at
          <ulink url="http://bugs.eclipse.org/bugs">http://bugs.eclipse.org/bugs</ulink>
          (using the product <literal>AspectJ</literal>).  Here are direct links to
              <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&amp;component=Compiler&amp;bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED">
               view open compiler bugs</ulink>,
              <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ">
               view all Aspectj bugs (open or closed)</ulink>, or
              <ulink url="http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ">
               add new bugs</ulink>.
          </para>
        </answer>
      </qandaentry>
      
      <qandaentry>
        <question id="q:mailingLists"
            xreflabel="Q: What mailing lists are there?">
          <para>What mailing lists are there?</para>
        </question>
        <answer>
          <para>
            The AspectJ users mailing list 
            (<literal>aspectj-users@eclipse.org</literal>)
            provides an informal network of AspectJ language users who
            can answer usage questions about AspectJ programs
            and the AspectJ tools.
            This is the place to ask how to code something in AspectJ
            or how to write Ant or shell scripts to invoke the tools.
          </para>
          <para>
            The AspectJ developers mailing list 
            (<literal>aspectj-dev@eclipse.org</literal>)
            provides an informal network of AspectJ technology experts who
            aim to understand the technology behind AspectJ.
            The committers to the AspectJ project use this list
            for open technical and planning discussions.
            Developers can answer questions about what's possible and about
            integrating AspectJ technology with other technologies.
          </para>
          <para>
            For both mailing lists, only subscribed members may post messages.
            To subscribe, visit the 
            <ulink url="http://eclipse.org/aspectj">AspectJ web site</ulink>.
          </para>
          <para>
            There you can also subscribe to 
            <literal>aspectj-announce@eclipse.org</literal>,
            a low-traffic list containing only announcements
            about significant AspectJ events and product releases.
            To get on a similar list for aspect-oriented software 
            development generally, see
            <ulink url="http://aosd.net">http://aosd.net</ulink>.
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="compiler" xreflabel="Using the AspectJ compiler">
      <title>Using the AspectJ compiler</title>
      <qandaentry>
        <question id="q:compilerRequired"
            xreflabel="Q:Do I have to use the AspectJ compiler?">
          <para>
            Do I have to use the AspectJ compiler?
          </para>
        </question>
        <answer>
            <para> The AspectJ compiler or weaver is required at some point, but
                many people can use AspectJ without changing their build or
                deployment process significantly. For aspects that are not
                required to compile, you can use the AspectJ binary weaver, run
                at build-time or class-load-time. You can write aspects using
                the original code style (which must be compiled with the AspectJ
                compiler) or using the annotation style new in AspectJ 5 (which
                may be compiled with Javac or the AspectJ compiler). </para>
          <para>
              For more information, see
              <xref linkend="q:codeversusannotationstyles"/>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:requiredsources"
            xreflabel="Q:What files do I need to include when compiling AspectJ programs?">
          <para>
            What files do I need to include when compiling AspectJ programs?
          </para>
        </question>
        <answer>
          <para>You need to specify to the compiler the files that
            contain your aspects and the files that contain the 
            types affected by your aspects.
	    See <xref linkend="q:knowWhenAspectsAffectClasses"/>.
	    The AspectJ compiler will not search the source path for types
	    that may be affected (unlike Javac and Jikes).
	    In AspectJ 1.0, ajc requires all code to be in source form;
	    in AspectJ 1.1, Java and AspectJ code may be in either source
	    or binary form.  
          </para>
          <para>In some cases you should compile your entire system all at once.
           If this is too slow, then you can try to make reasonable divisions
           between sets of source files whose aspects do not interact to 
           achieve a shorter compile cycle (particularly for development 
	       aspects).  If you have aspects that apply to different modules,
	       you can try compiling them into a binary form and using them
	       to weave each module.  However, if you get any problems
           or if you wish to run tests or do a release, you should recompile
           the entire system.
          </para>
          <para>
          For more information, see the 
            <ulink url="devguide/index.html">
              Development Environment Guide</ulink>
            <ulink url="devguide/ajc-ref.html">
              Reference for ajc</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:listingsources"
            xreflabel="Q:Is there any other way to provide the file names to ajc?">
          <para>I have to list many files in the command line to
            compile with <literal>ajc</literal>. Is there any other way to
            provide the file names to <literal>ajc</literal>?
          </para>
        </question>
        <answer>
          <para>
          Yes, use the argfile option to ajc. List source 
          files in a line-delimited text file and direct ajc to that 
          file using <literal>-argfile</literal> or <literal>@</literal>:
          </para>
          <programlisting>ajc @sources.lst
ajc -argfile sources.lst
          </programlisting>
          <para>Another way in AspectJ 1.1 is to use the 
          	<literal>-sourceroots</literal> options, which reads all
          	source files in a given set of directories:
          </para>
          <programlisting>ajc -sourceroots "src;testsrc"
          </programlisting>
          <para>
          For more information, see the 
            <ulink url="devguide/index.html">
              Development Environment Guide</ulink>
            <ulink url="devguide/ajc-ref.html">
              Reference for ajc</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:compilerVM"
            xreflabel="Q: What Java virtual machine (JVM) do I use to run the
             AspectJ compiler? ">
          <para>What Java virtual machine (JVM) do I use to run the
            AspectJ compiler?
          </para>
        </question>
        <answer>
          <para>Use the latest, greatest, fastest JVM you can get your hands on
            for your platform. The compiler's performance is dependent on the
            performance of the JVM it is running on, so the faster a JVM you
            can find to run it on, the shorter your compile times will be. At a
            minimum you need to use a Java 2 or later JVM to run the compiler
            (J2SE 1.3 for AspectJ 1.1).
            We realize that this constraint can be a problem for users who 
            don't currently have a Java 2 JVM available. We're sorry for the
            inconvenience, but we had to make the hard decision that the
            advantages of being able to rely on Java 2 were worth the cost of
            losing a number of developers who are working on platforms without
            Java 2 support. Here is a list of starting places where you might
            find support for your system.
            <itemizedlist>
              <listitem>
                <para>
                  <ulink url="http://java.sun.com/j2se/">Java 2
                    Platform, Standard Edition
                  </ulink>
                </para>
              </listitem>
              <listitem>
                <para>
                  <ulink
                      url="http://www-106.ibm.com/developerworks/java/jdk/">
                    developerWorks : Java technology : Tools and products - Developer kits
                  </ulink>
                </para>
              </listitem>
              <listitem>
                <para>
                  <ulink
                      url="http://www-124.ibm.com/developerworks/oss/jikes/">
                    developerWorks : Open Source - Jikes Project
                  </ulink>
                </para>
              </listitem>
              <listitem>
                <para>
                  <ulink url="http://java.sun.com/cgi-bin/java-ports.cgi">Java
                    Platform Ports
                  </ulink>
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>The requirement of Java 2 support is only for
            <emphasis>running</emphasis> the AspectJ compiler. The AspectJ
            compiler can be used to build programs that will run on Java 1.1
            (or probably even on Java 1.0) systems. This means that it can
            build programs that will run on Macintosh, FreeBSD, and applets
            that will run in Internet Explorer and Netscape Navigator that are
            still not yet Java 2 compliant.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:compilingForDifferentVMs"
            xreflabel="Q: How to use ajc to compile for a different VM?">
          <para>How can I use <literal>ajc</literal> to compile
            programs for a JVM that is different from the one used to run it?
          </para>
        </question>
        <answer>
          <para>
            <literal>ajc</literal> can be used to develop programs that are
            targeted at the Java 1.1 platform, even though the
            <literal>ajc</literal> compiler won't run on that platform. Here's
            an example of using <literal>ajc</literal> in this sort of
            cross-compilation mode (assuming a Windows platform with all the
            default installation directories):
          </para>
          <programlisting>
ajc -target 1.1 -bootclasspath c:\jdk1.1.7\lib\classes.zip \
   -classpath c:\aspectj1.0\lib\aspectjrt.jar -extdirs "" \
   -argfile jdk11system.lst
          </programlisting>
          <para>This same technique can be used if you want to run
            <literal>ajc</literal> on a JDK 1.3 JVM (highly recommended) but
            need to generate code for JDK 1.2. That would look something
            like:
          </para>
          <programlisting>
ajc -bootclasspath c:\jdk1.2\jre\lib\rt.jar \
   -classpath c:\aspectj1.0\lib\aspectjrt.jar \
    -extdirs c:\jdk1.2\jre\lib\ext
            -argfile jdk12system.lst
          </programlisting>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:assert"
            xreflabel="Q:Does the ajc compiler support the assert keyword in Java 1.4?">
          <para>Does the <literal>ajc</literal> compiler support 
        the <literal>assert</literal> keyword in Java 1.4?
          </para>
        </question>
        <answer>
          <para>Yes. As with <literal>Javac</literal>,
          use the <literal>-source 1.4</literal> option as described
          in the
            <ulink url="devguide/index.html">
              Development Environment Guide</ulink>
            <ulink url="devguide/ajc-ref.html">
              Reference for ajc</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:generics"
            xreflabel="Q:Does the ajc compiler support generics and the other new language features of Java 5?">
          <para>Does the <literal>ajc</literal> compiler support 
        generics and the other new language features of Java 5?
          </para>
        </question>
        <answer>
          <para>Yes. As with <literal>Javac</literal>,
          use the <literal>-1.5</literal> option as described
          in the
            <ulink url="devguide/index.html">
              Development Environment Guide</ulink>
            <ulink url="devguide/ajc-ref.html">
              Reference for ajc</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:versionCompatibility"
            xreflabel="Q:Will AspectJ aspects work with different versions of the compiler/weaver and runtime?">
          <para>Will aspects work with different versions of the compiler/weaver and runtime?
          </para>
        </question>
        <answer>
          <para>Yes.  Both <literal>ajc</literal> and 
			  <literal>aspectjrt.jar</literal> should work with versions
			  of aspect code and libraries back to AspectJ 1.2.1. 
			  Any aspects should be deployed
			  with the same version of <literal>aspectjrt.jar</literal> 
			  they were compiled with.  For more information, see the
			 <ulink url="devguide/index.html">
              Development Environment Guide</ulink>
            <ulink url="devguide/ajc-ref.html">
              Reference for ajc</ulink>
			  and 
            <ulink url="devguide/deployment.html">
              Deployment notes</ulink> section on 
            <ulink url="devguide/versionCompatibility.html">
				Version compatibility</ulink>.
			</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:msjvm"
            xreflabel="Q:Are there any issues using AspectJ with the Microsoft JVM?">
          <para>Are there any issues using AspectJ with the Microsoft
            JVM?
          </para>
        </question>
        <answer>
          <para>Since AspectJ requires Java 2 or later, it will not run on the
            Microsoft JVM, which does not support Java 2.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:javacbytecode"
            xreflabel="Q:Does ajc rely on javac for generating bytecode?">
          <para>Does <literal>ajc</literal> rely
            on <literal>javac</literal> for generating Java bytecode
            (<literal>.class</literal>) files?
          </para>
        </question>
        <answer>
          <para> No.  Some previous versions of AspectJ had this requirement.
          In AspectJ 1.0, <literal>javac</literal> can still be used as
          <literal>ajc</literal> back end by using the
          <literal>-usejavac</literal> flag.  You can also run <literal>ajc</literal>
          in preprocessor mode to generate Java source
          (<literal>.java</literal>) files to be compiled using
          <literal>javac</literal> or another java compiler.
          Neither option is supported in AspectJ 1.1.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:parsergenerators"
            xreflabel="Q:I noticed the AspectJ compiler doesn't use a parser generator.  Why is that?">
          <para>
            I noticed the AspectJ compiler doesn't use a parser generator.  Why is that?
          </para>
        </question>
        <answer>
          <para>In AspectJ 1.0,
          the PARSER for ajc is written by hand.  This choice was made with full 
          awareness of the generator tools out there.  (Jim had for example used 
          the excellent javacc tool for building the parser for JPython (now Jython)).  
          One of the reasons that AspectJ uses a hand-written parser is that using 
          javacc taught Jim about the LL-k design for parsers (pioneered by antlr).  
          As opposed to the state-machine parsers produced by yacc, these parsers are 
          very readable and writable by humans.
          </para>
          <para>
            Antlr and javacc did not really suit the project:
          </para>
          <itemizedlist>
            <listitem>
              <para>
            Antlr's support for unicode in the lexer is still immature and this makes 
            using it with Java challenging.  This was an even bigger issue 3 years ago 
            when we started on the Java implementation of ajc.
              </para>
            </listitem>
            <listitem>
              <para>
            While javacc is freely available, it is not Open Source.  Depending on a 
            closed-source tool to build an Open Source compiler would reduce some 
            of the transparency and control of open-source.
              </para>
            </listitem>
          </itemizedlist>
          <para>
          There were also several things that were easier to implement with 
          a hand-written parser than with any of the exiting tools.
          </para>
          <itemizedlist>
            <listitem>
              <para>
            Semi-keywords -- it's important to us that 
            "every legal Java program is also a legal AspectJ program."  
            This wouldn't be true if we made 'before' and 'call' full keywords in 
            AspectJ.  It is easier to support these sorts of semi-keywords with a 
            hand-written parser.  (Note: ajc-1.0.x handles 'aspect' and 'pointcut' 
            slightly specially which can break a few unusual pure Java programs.  
            This is a compiler limitation that will be fixed in a future release.)
              </para>
            </listitem>
            <listitem>
              <para>
            Deprecated syntax warnings -- the syntax of AspectJ 
            changed many times from version 0.2 to the 1.0 release.  It was easier 
            to provide helpful warning messages for these changes with our 
            hand-written parser.
              </para>
            </listitem>
            <listitem>
              <para>
            Grammar modularity -- We like being able to have 
            AspectJParser extend JavaParser.
              </para>
            </listitem>
            <listitem>
              <para> 
            Part of the grammar for AspectJ is extremely hard for existing tools to 
            capture. This is the type pattern syntax, i.e. "com.xerox..*.*(..)".  
            The sort of case that gives standard parser generators fits is something 
            like "*1.f(..)" which no one would ever write, but which must be 
            supported for a consistent language.
              </para>
              <para>
              In AspectJ 1.1, the parser was written as it is for the underlying
              Eclipse compiler,
              with some hand-coding of the sort that avoids adding keywords to
              the language.
              </para>
            </listitem>
          </itemizedlist>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:howIncrementalWorks"
            xreflabel="Q: How does incremental mode work?">
          <para>How does incremental mode work?
          </para>
        </question>
        <answer>
              <para>In incremental mode, ajc minimizes the files that need
                  to be recompiled after another file has changed.  In Java,
                  only the changed files need to be recompiled, but in AspectJ,
                  other files might also need to be recompiled or re-woven.
              </para>
                <para> Depending on what is modified, we may need to re-weave
                    code.  If you change a pointcut and save it, we currently have
                    to check everywhere in case a new match is occurring or an old
                    match is no longer correct.  However, if you simply change
                    the body of an advice in an aspect, there is (usually) no need
                    to reweave as the affected classes call the advice and the
                    advice (by design) maintains its name in the recompiled
                    aspect. </para>
                <para> If you make a change to a class (as opposed to an aspect) and
                    save it, we usually can get away with merely having to
                    compile that class then weave the existing aspects with it -
                    rather than doing a full recompile of the entire system.
                    </para>
                <para> There are a lot of possible optimizations to the
                    algorithms we use, by performing more complete analysis of
                    the change made to a file that will enable us to know more
                    accurately whether we need to reweave and if we do then what
                    we need to reweave - we just haven't gotten around to
                    implementing them yet. </para>
        </answer>
      </qandaentry>
            </qandadiv>
    <qandadiv id="devtools" xreflabel="Integrating AspectJ into your development environment">
      <title>Integrating AspectJ into your development environment</title>
      <qandaentry>
        <question id="q:knowWhenAspectsAffectClasses"
            xreflabel="Q: How do I know which aspects affect a class when looking at that class's source code?">
          <para>How do I know which aspects affect a class when looking
            at that class's source code?
          </para>
        </question>
        <answer>
          <para>When you are working with the IDE support, you can get an
            understanding of which aspects affect any class.
            This enables AspectJ programmers to get the benefits of
            modularizing crosscutting concerns while still having immediate
            access to what aspects affect a class.
          </para>
          <para>For example, the
            <ulink url="devguide/index.html">
              Development Environment Guide</ulink>
            <ulink url="devguide/ajbrowser.html">
              ajbrowser section</ulink>.
          shows that you can list or navigate
          between method and advice affecting that method and between a type
          and declarations in an aspect on that type.  (The IDE support may
          have more features than <literal>ajbrowser</literal>, depending
          on the IDE.
          See <xref linkend="q:integrateWithDevTools"/> for more
            information on which Java development environments are
            supported.)
          </para>
          <para>
            When you are looking at documentation for AspectJ 1.0 programs,
            <literal>ajdoc</literal> will provide links from aspects and
            advice to the affected code, but it provides less information
            than the IDE support because it only parses declarations.
          </para>
          <para>
            When you are compiling your program, pointcuts that are
            statically-determinable can be used in declare statements
            to identify the code picked out by the pointcut.
            (A pointcut is statically determinable if it only uses
             the pointcut designators
             <literal>within</literal>,
             <literal>withincode</literal>,
             <literal>execution</literal>,
             <literal>call</literal>,
             <literal>get</literal>,
             <literal>set</literal>,
             <literal>initialiation</literal>, and
             <literal>staticinitialiation</literal>.)
             The compiler will list the static code points which will be 
             affected by any advice specifying the same pointcut.
             For example, the following will print a warning
             whereever some code in class Bar gets a field value from Foo:
             <programlisting>
  declare warning: get(* Foo.*) &amp;&amp; within(Bar) 
     : "reading Foo state from Bar";
             </programlisting>
          </para>
          <para>
            When you are running your program,
            you can trace advice as it executes.  This
            enables you to identify advice on join points picked out 
            dynamically, which cannot be reflected precisely by IDE support.
            For a related tracing question,
               see <xref linkend="q:seeingjoinpoints"/>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:idesupport"
            xreflabel="Q:What kind of IDE support is available for developing AspectJ programs?">
          <para>What kind of IDE support is available for developing
            AspectJ programs?
          </para>
        </question>
        <answer>
          <para>See <xref linkend="q:integrateWithDevTools"/></para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:idesupportplans"
            xreflabel="Q:What plans are there to support my IDE?">
          <para>What plans are there to support my IDE?</para>
        </question>
        <answer>
          <para>
            The AspectJ team directly provided components for JBuilder, Forte,
            and Emacs and supported the open-source AspectJ plugin project
            at <ulink url="http://eclipse.org/ajdt">http://eclipse.org/ajdt</ulink>
            which uses the AJDE API support for IDE's.  
            Supporting new IDE's is a matter of building on the AJDE API's,
            mostly likely adopting one of the existing open-source IDE
            extensions as a design template.
            Here are the IDE's where we know people have expressed interest,
            so interested developer may want to join with others in their
            developer communities to build the integration.
            <itemizedlist>
              <title></title>
              <listitem>
                <para>IDEA/IntelliJ has an enthusiastic community and 
                the developers are working on an extensibility API
                - <ulink url="http://intellij.com">http://intellij.com</ulink>
                </para>
              </listitem>
              <listitem>
                <para>jEdit comes from a very active open-source community.</para>
              </listitem>
              <listitem>
                <para>
                  Oracle JDeveloper is supported at
                  <ulink url="https://jdeveloperaop.dev.java.net/">
					https://jdeveloperaop.dev.java.net/</ulink>.
                </para>
              </listitem>
              <listitem>
                <para>Some have suggested Codeguide from Omnicore
	         <ulink url="http://www.omnicore.com">http://www.omnicore.com/</ulink>
                </para>
              </listitem>
            </itemizedlist>
          </para>
          <para>
            For questions on AJDE, join the developer's list
            <literal>aspectj-dev@eclipse.org</literal>.
            For questions on the current IDE integrations, contact those projects.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:portingajde"
            xreflabel="Q:Can I port AJDE support to my development environment?">
          <para>Can I port AJDE support to my development environment?</para>
        </question>
        <answer>
          <para>Yes. The core AJDE API is extensible and the source code is
            available for download. Start by studying the sources
            for the existing IDE support linked off the AspectJ site
            <ulink url="http://eclipse.org/aspectj">http://eclipse.org/aspectj</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:hybridbuilds"
            xreflabel="Q:Setting up hybrid builds">
          <para>I want the aspects for development builds but 
        remove them for production builds.  How can I set up the build
        system so they are unpluggable?  And so I use <literal>javac</literal>
        in my production build?
          </para>
        </question>
        <answer>
          <para>
          If you are using development-time-only aspects - aspects that only 
          exist when you are developing the code, not when you ship it - 
          you can use implement a hybrid build process by listing
          the production source files into a javac-compliant argfile,
          and the development source files in another ajc argfiles:
          </para>
          <programlisting>
     -- file "production.lst":
     One.java
     two/Three.java
     ...

     -- file "tracing.lst":
     trace/Library.java
     Trace.java

     -- file "development.lst":
     @production.lst
     @tracing.lst
          </programlisting>
          <para>
            Then your development build can use <literal>ajc</literal>:
          </para>
          <programlisting>
            ajc @development.lst
          </programlisting>
          <para>
          And your development build can use 
          <literal>ajc</literal> or <literal>javac</literal>
           or <literal>jikes</literal>:
          </para>
          <programlisting>
            jikes @production.lst
          </programlisting>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:stepwiseBuilds"
            xreflabel="Q:We compile module jars and then assemble them.  Can we continue this with AspectJ?">
          <para>
            We compile module jars and then assemble them.  Can we continue this with AspectJ?
          </para>
        </question>
        <answer>
          <para>
		Aspects apply to everything in a namespace, as if everything is 
		compiled together.
		Sometimes you can break the build down into separate steps without breaking 
		this model, but we haven't stated exactly where it could break
		because it depends on the interactions between all types.
		You can try the approaches below, but remember to rebuild 
		everything in one go if there are problems.
		</para>
		<para>
		The simplest scenario is when the aspects apply to all modules
		and the modules compile without the aspects.  In that case,
		weaving in the aspects is just the final assembly step for
		the build.
		</para>
		<para>
		Next is the case where the aspects make changes to a common
		library that are visible to other clients, which themselves
		are otherwise unaffected by the aspects.  In this case, the
		common library can be built using ajc, and used on the 
		classpath for the module builds:
		<programlisting>
<![CDATA[
   ajc -outjar common.jar -sourceroots "aspectj-src:src" ...
   cd ../otherProject
   javac -classpath "../common/common.jar:${aspectjrt.jar}" {src}
]]>
		</programlisting>
		</para>
		<para>
		Combining these last two, 
		there's the case where a common set of aspects should
		affect two or more modules that are in a dependency relationship
		to one another.  It should work to reuse the aspects 
		in binary form for each compile, in dependency order:
		
		<programlisting>
<![CDATA[
   ajc -outjar common-aspects.jar
       -sourceroots "aspectj-src" ...

   ajc -outjar common.jar
       -sourceroots "src"
       -aspectpath common-aspects.jar ...

   cd ../module1
   ajc -outjar module1.jar
       -sourceroots "src"
       -classpath common.jar
       -aspectpath ../common-aspects.jar ...

   cd ../module2
   ajc -outjar module2.jar
       -sourceroots "src"
       -classpath "common.jar;../module1.jar"
       -aspectpath ../common-aspects.jar ...
]]>
		</programlisting>   
		</para>
		<para>
		If two modules are visibly affected by aspects and
		mutually-dependent, the only thing to do is compile
		them together.
		</para>
		<para>
		It's safest to assume that all aspects can affect all
		types in a namespace; using build boundaries to effect
		crosscutting limits causes a dangerous dependency on
		the build process and might cause problems.
		</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:incrementalModuleCompiles"
            xreflabel="Q: We use modules and would like to use incremental compilation.
                          Is that possible?">
          <para>We use modules and would like to use incremental compilation.
                Is that possible?
          </para>
        </question>
        <answer>
          <para>
			Just incrementally-compile the whole system.
			Specify to ajc the modules as multiple source roots  
			(or input jars if you are weaving libraries).
			</para>
			<para>
			In Eclipse's AJDT, you can create a top-level project with symbolic 
			links out to the sources:
			
			<programlisting>
<![CDATA[
   app-assembly/
	 {link common/aspects}
	 {link common/src}
	 {link module1/src}
	 ...
]]>
			</programlisting>   
			
			Then everything is part of one huge incremental compile.  Also, you
			can close this master project and work the others using the Java
			compiler or AJDT.
			</para>
			<para>
			The links make incremental development possible without affecting
			the modularized Ant builds.  (Our practice runs along those lines.)
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="notes" xreflabel="Programming notes and tips">
      <title>Programming notes and tips</title>
      <qandaentry>
        <question id="q:methodsignatures"
            xreflabel="Q:Is it possible to change methods by introducing keywords, adding parameters, or changing the throws clause?">
          <para>Is it possible to change methods by introducing keywords (like
            <literal>synchronized</literal>), adding parameters, 
                     or changing the "throws" clause?
          </para>
        </question>
        <answer>
          <para>AspectJ does not enable you to change the signature of a method,
            but you can (by express declaration) work around some 
            limits imposed by the signature.  You can convert a checked exception to
            unchecked using <literal>declare soft</literal>, privileged aspects
            have access to private methods, and you can use a percflow aspect to 
            ferry additional state to a callee without changing intervening 
            signatures.   For more details, see
            <ulink url="progguide/index.html">The AspectJ Programming Guide</ulink>.
            In the case of <literal>synchronized</literal>,
            we have what we consider a better solution that uses
            around advice instead of introduction.  This solution is described
            in
            <ulink url="http://aspectj.org/pipermail/users/2000/000534.html">
              this thread (no longer available)
            </ulink> on the AspectJ users list, with some
            <ulink url="http://aspectj.org/pipermail/users/2000/000536.html">
              additional comments (no longer available)
            </ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:seeingjoinpoints"
            xreflabel="Q:I don't understand what join points exist.  How can I see them?">
          <para>
            I don't understand what join points exist.  How can I see them?
          </para>
        </question>
        <answer>
          <para>
          You can trace them using using an aspect.
           For example, you can start logging at a particular method call and 
	   see what join points occur after the call and before it returns.
          </para>
          <para>
          Here's some code Jim Hugunin wrote to trace join points
          and posted to the users list. To reuse the aspect, 
          define a subaspect and implement the pointcuts, for example:
          <programlisting>

aspect JoinPointSampleAspect extends aj.TraceJoinPoints {
    protected pointcut entry() : 
        execution(static void JoinPointSample.main(String[]));
    protected pointcut exit() : 
        call(static void JoinPointSampleAspect.exit());

    public static void main (String[] args) {
        JoinPointSample.main(args);   
        JoinPointSampleAspect.exit();   
    } 
    public static void exit() {}
}

class JoinPointSample {
    public static void main(String[] args) {}
}
          </programlisting>
          </para>
          <para>Here's the aspect:
          <programlisting>
<![CDATA[
/* TraceJoinPoints.java */

package aj;

import org.aspectj.lang.*;
import org.aspectj.lang.reflect.*;
import java.io.*;

public abstract aspect TraceJoinPoints {
    protected abstract pointcut entry();
    protected pointcut exit(): call(* java..*.*(..));
    // this line is for AspectJ 1.1; for 1.0, use "dominates"
    declare precedence : TraceJoinPoints, *;
    final pointcut start(): entry() && !cflowbelow(entry());

    final pointcut trace():
        cflow(entry()) && !cflowbelow(exit()) && !within(TraceJoinPoints+);

    before(): start() { makeLogStream(); }

    before(): trace() { logEnter(thisJoinPointStaticPart); }
    after(): trace() { logExit(thisJoinPointStaticPart); }

    after(): start() { closeLogStream(); }

    //------------ added
    /**
     * Emit a message in the log, e.g.,
     * <pre>TraceJoinPoints tjp = TraceJoinPoints.aspectOf();
     * if (null != tjp) tjp.message("Hello, World!");</pre>
     */
    public void message(String s) {
        out.println("<message>" + prepareMessage(s) + "</message>");
    }
    public void message(String sink, String s) {
        if (null == sink) {
            message(s);
        } else {
            out.println("<message sink=" + quoteXml(sink)
                        + " >" + prepareMessage(s) + "</message>");
        }
    }
    protected String prepareMessage(String s) { return s; } // XXX implement

    //--------- end of added

    PrintStream out;
    int logs = 0;
    protected void makeLogStream() {
        try {
            out = new PrintStream(new FileOutputStream("log" + logs++ + ".xml"));
        } catch (IOException ioe) {
            out = System.err;
        }
    }

    protected void closeLogStream() {
        out.close();
    }


    int depth = 0;
    boolean terminal = false;
    protected void logEnter(JoinPoint.StaticPart jp) {
        if (terminal) out.println(">");
        indent(depth);
        out.print("<" + jp.getKind());
        writeSig(jp);
        writePos(jp);

        depth += 1;
        terminal = true;
    }

    void writeSig(JoinPoint.StaticPart jp) {
        out.print(" sig=");
        out.print(quoteXml(jp.getSignature().toShortString()));
    }

    void writePos(JoinPoint.StaticPart jp) {
        SourceLocation loc = jp.getSourceLocation();
        if (loc == null) return;

        out.print(" pos=");
        out.print(quoteXml(loc.getFileName() +
                           ":" + loc.getLine() +
                           ":" + loc.getColumn()));
    }

    String quoteXml(String s) {
        return "\"" + s.replace('<', '_').replace('>', '_') + "\"";
    }

    protected void logExit(JoinPoint.StaticPart jp) {
        depth -= 1;
        if (terminal) {
            out.println("/>");
        } else {
            indent(depth);
            out.println("</" + jp.getKind() + ">");
        }
        terminal = false;
    }

    void indent(int i) {
        while (i-- > 0) out.print("  ");
    }
}
]]>
          </programlisting>
          </para>
          <para>Note that if you are using AspectJ 1.0,
          	the line starting with <literal>declare precedence</literal>
          	would be removed, and the aspect declaration would look like
          	<literal>aspect TraceMyJoinPoints dominates *</literal>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:comparecallandexecution"
            xreflabel="Q:What is the difference between call and execution join points?">
          <para>
            What is the difference between call and execution join points?
          </para>
        </question>
        <answer>
          <para>
	    Briefly, there are two interesting times when a constructor or method is
	    run.  Those times are when it is called, and when it actually
	    executes.
          </para>
          <para>
	    The main difference is that a call join point happens outside of
	    the target object (for non-static methods) or class (for static methods
	    and constructors), and that an execution join point happens inside
	    the object or class.  This means that the <literal>within</literal>
	    and <literal>withincode</literal> pointcuts pick them out
	    differently: A call join point is picked out within the caller,
	    while an execution join point is picked
	    out where it is actually defined.
          </para>
          <para>
	    A call join point is the ``outermost'' join point for a particular
	    call.  Once a call join point proceeds, then a number of different
	    things happen.  For non-static methods, for example, method
	    dispatch happens, which will cause one method execution join point
	    -- perhaps more, if there are super calls.  For constructors, the
	    super constructor is called, and fields are initialized, and then
	    various constructor execution join points will occur.
          </para>
          <para>
	    A call join point matches only the ``external'' calls of a method
	    or constructor, based on a signature, and it does not pick out
	    calls made with <literal>super</literal>, or
	    <literal>this</literal> constructor calls.
          </para>
          <para>Here's more detail:
          </para>
          <para>Consider method execution in Java as (1) the initial call from
                this object to some method on the target object with a
                particular signature; and (2) the execution of the actual code
                in the particular method dispatched in the target object.
                The call join point starts with the initial call and ends 
                when control returns to the call (by return or perhaps 
                thrown exception).  The execution join point starts with
                the method body and ends when the body completes (again
                by return or throwing an exception), so the execution join
                point always happens within the bounds of the corresponding
                call join point.  You can see this if you use the
	        join-point tracing aspect in see <xref linkend="q:seeingjoinpoints"/>.
          </para>
          <para>As you would expect, the context differs 
                in advice on pointcuts picking out execution and call join
                points; for call, <literal>this</literal> refers to the caller, whereas 
                for execution <literal>this</literal> refers to the called 
                (executing) object.
          </para>
          <para>
	There are some subtle interactions with other AspectJ semantics.
	First, the meaning of the signature in the
	<literal>execution()</literal> and <literal>call()</literal>
	pointcut designators (PCD's) differ: the call type depends upon
	the type of the reference making the call, while the execution
	type depends on the enclosing class.
        Second, you may choose one over another if you cannot bring all
	your sources within the code the compiler controls
	(described in the <ulink url="progguide/semantics.html">appendix</ulink>
     to the <literal>Programming Guide</literal>).
	For example, to trace calls into a 
	method from classes which are outside the code the compiler controls
	at compile time, then using <literal>execution()</literal> will work
	while using <literal>call()</literal>may not.  Finally, since 
	<literal>super</literal> invocations are not considered method calls,
	to trace <literal>super.foo()</literal> would require using
	<literal>execution</literal>.
          </para>
          <para>
          		Because of differences in the way AspectJ 1.0 and 1.1
          		are implemented, in 1.0
                you should use the <literal>call()</literal> 
                pointcut designator unless you have a good reason to use
	        <literal>execution()</literal>; in AspectJ 1.1, the 
	        reverse is true.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:comparecflowandcflowbelow"
            xreflabel="Q:What is the difference between cflow and cflowbelow?">
          <para>
            What is the difference between cflow and cflowbelow?
          </para>
        </question>
        <answer>
          <para>
	    Both pick out all the join points in the control flow of
	    the specified join points.
            They differ only in that the <literal>cflowbelow()</literal>
	    pointcut designator does not pick out the join points
	    specified, while <literal>cflow()</literal> does.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:recursiveentrypoints"
            xreflabel="Q:How do I say that I want the topmost entrypoint in a recursive call?">
          <para>How do I say that I want the topmost entrypoint in a
	        recursive call? How about the most-recent prior entrypoint?
          </para>
        </question>
        <answer>
          <para>This is best seen by way of example.
	Given a recursive call to <literal>int factorial(int)</literal>
	  you can print the arguments for 
	(a) the current and most-recent recursive call
	or (b) the current and original recursive call:
          </para>
          <programlisting>
aspect LogFactorial {
    pointcut f(int i) : call(int factorial(int)) &amp;&amp; args(i);

    // most-recent
    before(int i, final int j) : f(i) &amp;&amp; cflowbelow(f(j)) { 
        System.err.println(i + "-" + j);
    }

    // original
    before(int i, final int j) : f(i) 
        &amp;&amp; cflowbelow(cflow(f(j)) &amp;&amp; !cflowbelow(f(int))) { 
        System.err.println(i + "@" + j);
    }
}
          </programlisting>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:initializationjoinpoints"
            xreflabel="Q:What is the difference between constructor call, constructor execution, initialization, and static initialization join points?">
          <para>What is the difference between constructor call, 
          constructor execution, initialization, and static 
          initialization join points?
          </para>
        </question>
        <answer>
          <para>Static initialization pertains to initialization of
          a class or interface type. Constructor call and execution
          are akin to method call, and initialization generalizes this and
          picks out the first constructor called.
          </para>
          <para>Their relations are best 
          demonstrated by tracing the join points.  Below is the class
          Test which implements an interface and extends a class
          along with a trace of the join points below and including
          the constructor call obtained using 
          <literal>TraceJointPoints.java</literal>
               from <xref linkend="q:seeingjoinpoints"/>.
          </para>
          <programlisting>
            <![CDATA[
public class Init {
    public static void main (String[] args) {
        new Test(); 
        end();
    } 
    static void end() {}
}
class Super {}
interface I {}
class Test extends Super implements I {
    Test() {}
}

]]>
          </programlisting>
          <para>For a program compiled with AspectJ 1.0, 
          	the result is this:</para>
          <programlisting>
            <![CDATA[
  <constructor-call sig="Test()" >
    <staticinitialization sig="Super._init_" />
    <staticinitialization sig="Test._init_" />
    <initialization sig="Super()" >
      <instanceinitializer-execution sig="Super._init_" />
      <constructor-execution sig="Super()" />
    </initialization>
    <initialization sig="I()" >
      <instanceinitializer-execution sig="I._init_" />
      <constructor-execution sig="I()" />
    </initialization>
    <initialization sig="Test()" >
      <instanceinitializer-execution sig="Test._init_" />
      <constructor-execution sig="Test()" />
    </initialization>
  </constructor-call>
]]>
          </programlisting>
          <para>
        Ordinarily, using a <literal>call</literal> pointcut designator 
        is best because the call join point surrounds the others, but in
        the case of constructors there is no target object for
        the call (because it has not been constructed yet), so you
        might prefer to use the <literal>initialization</literal> 
        pointcut designator.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:adviseconstructors"
            xreflabel="Q:How do I work with an object right when it is created?">
          <para>How do I work with an object right when it is created?
          </para>
        </question>
        <answer>
          <para>
          You can advise some form of constructor join point.
          Constructors are tricky in Java, and that's exposed in AspectJ.  
          Here are some rules of thumb:
          <itemizedlist>
            <listitem>
              <para>If you want the join point on the "outside" of object creation, 
              use after returning from call to the constructor:
              </para>
              <programlisting>
    after() returning (Foo newlyCreatedObject): call(Foo.new(..)) { ... }
              </programlisting>
              <para>
  You might be tempted to use "this" or "target" to expose the new object, but remember
  that if you're on the "outside" of object creation, the object itself might not be
  created yet... it only exists "on the way out", when you return the object.
              </para>
            </listitem>
            <listitem> 
              <para>If you want the join point inside a particular constructor, use:
              </para>
              <programlisting>
    after(Foo newlyCreatedObject) returning: this(newlyCreatedObject) &amp;&amp; execution(Foo.new(..)) { ... }
              </programlisting>
              <para>
    Remember, though, that if you use "before" advice here, the body of the constructor
    will not have run, and so the object may be somewhat uninitialized.
              </para>
            </listitem>
            <listitem> 
              <para>
    In the rare case that there are all sorts of constructors for the object that call 
    each other with <literal>this(...)</literal> and you want exactly one join point 
    for each initialization of <literal>Foo</literal>, regardless of the path of 
    constructors it takes, then use:
              </para>
              <programlisting>
    after(Foo f) returning: this(f) &amp;&amp; initialization(Foo.new(..)) { ... }
              </programlisting>
            </listitem> 
          </itemizedlist>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:andingpointcuts"
            xreflabel="Q:I want advice to run at two join points, but it doesn't run at all.">
          <para>
            I want advice to run at two join points, but it doesn't run at all.  What gives?
          </para>
        </question>
        <answer>
          <para>
	  This usually reflects both a conceptual error and a programming mistake.
	  Most likely you want to do something like "run the advice for all 
	public and private calls," and the code looks something like this:
          </para>
          <programlisting>
            within(com.xerox.printing..*) &amp;&amp; call(public * *(..)) &amp;&amp; call(private * *(..))
          </programlisting>
          <para>
	But a pointcut is evaluated at *each* join point.
        The expression above would never pick out any call join point,
	because no method signature has both public and private access.
	In a pointcut, <literal>pc1() &amp;&amp; pc2()</literal> means both
	must be true at a given join point for advice to run at that join point.
	The correct pointcut would use <literal>||</literal> as follows:
          </para>
          <programlisting>
            within(com.xerox.printing..*) &amp;&amp; (call(public * *(..)) || call(private * *(..)))
          </programlisting>
          <para>
            Then the advice will run at the join point.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:staticfieldreferences"
            xreflabel="Q:How do I refer to a static field when my advice crosscuts multiple classes?">
          <para>
            How do I refer to a static field when my advice crosscuts multiple classes?
          </para>
        </question>
        <answer>
          <para>There is no way in advice to refer to the type of the
	  code executing in a static context except by specification.
	  This makes it impossible to refer to static members using 
	  runtime information.
          </para>
          <para>However, AspectJ can determine the class for something
          	in the join point context, which you can use as a per-class key. 
          	Then you can actually declare an instance field to contain
          	the per-class value (see the next question).  This comes at
          	the cost of an extra reference, but the field can be final.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:interfacesastypepatterns"
            xreflabel="Q:How can I reuse a type pattern?">
          <para>I would like to reuse a type pattern, e.g., to
	write advice that is limited to a certain set of classes.
	Do I have to retype it each time?
          </para>
        </question>
        <answer>
          <para>No.  You can declare that all the types implement
	an interface you define, and then use the interface type in
	your program.  For example:
          </para>
          <programlisting>
/** 
 * Example of using an interface to represent a type pattern.
 * sub-aspects use declare parents to add to traced types, e.g.,
 *    declare parents: com.mycompany.whatever..* implements Marked;
 */
abstract aspect MarkerExample {
  /** marker interface for types that we want to trace */
  interface Marked {}

  /** calls to an instance of Marked not from an instance of Marked */
  pointcut dynamicCallsIn(): call(* *(..)) &amp;&amp; target(Marked) &amp;&amp; !this(Marked);

  /** calls to methods defined by a subtype of Marked
   *  that don't come from the body of a subtype of Marked
   */
  pointcut staticCallsIn(): call(* Marked+.*(..)) &amp;&amp; !within(Marked+);

  /** print dynamic calls */
  before(): dynamicCallsIn() { System.out.println("before " + thisJoinPoint); }
}

aspect MyMarker extends MarkerExample {
  declare parents: com.mycompany.whatever..* implements Marked;
}
          </programlisting>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:exampleprograms"
            xreflabel="Q:Where do I find example programs and how-to's?">
          <para>Where do I find example programs and how-to's?</para>
        </question>
        <answer>
          <para>There are a number of places to find sample code
           and instructions for using AspectJ with other programming tools.
		  <orderedlist>
			<listitem><para>
			The AspectJ release includes examples in its 
          	<literal>doc</literal> directory.
			</para></listitem>
			
			<listitem><para>
           There is a community repository of sample code and tutorials
           in the AspectJ CVS tree  
           <literal>docs</literal> module <literal>sandbox</literal> directory.
           These are extracted and published (online only) 
           <ulink url="http://dev.eclipse.org/viewcvs/indextech.cgi/~checkout~/aspectj-home/sample-code.html">
		   here
           </ulink>.
			</para></listitem>
			
			<listitem><para>
			The <literal>teaching</literal> directory of the 
			<literal>docs</literal> module contains public materials 
			the AspectJ committers use for presentations, some of 
			which include example code.  To access CVS, see
			<xref linkend="q:buildingsource"/>.			
			</para></listitem>
			
			<listitem><para>
			The archives for the user and developer mailing lists 
			contain many good examples.  To search the archives, see
			<xref linkend="q:searchingsite"/>.
			</para></listitem>
		  </orderedlist>
           This code can vary in quality.
           Code that we publish or include with AspectJ is generally
           correct.  However, code found in our CVS tree might not have 
           been tested thoroughly, and code from the mailing lists might
           be untested or use older versions of the language.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:aspectlibraries"
            xreflabel="Q:Are aspect libraries available?">
          <para>Are aspect libraries available?</para>
        </question>
        <answer>
          <para>Some libraries are distributed in the release under the
            examples folder in the distribution.
            These are "libraries" in the sense that they are reusable,
            but they are delivered in source form. 
            Similarly, some of the sample code is reusable; for that,
            see <xref linkend="q:exampleprograms"/>.
            If you develop such a library and want to make it available to 
            other users, feel to send it to the users mailing list
            <literal>aspectj-users@eclipse.org</literal>.
          </para>
          <para>In AspectJ 1.1, ajc supports binary aspects, so
          	you can distribute aspect libraries without distributing the
          	source.  For more information, see the 
          		<literal>-aspectpath</literal>
          	option in the 
          		<ulink url="devguide/ajc-ref.html">
              				Reference for ajc</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:serialversionuid"
            xreflabel="Q:How does ajc interact with the serialVersionUID?">
          <para>How does <literal>ajc</literal> interact with the
            <literal>serialVersionUID</literal>?
          </para>
        </question>
        <answer>
          <para>The current version of <literal>ajc</literal> can change the
            <varname>serialVersionUID</varname> of generated
            <filename>.class</filename> files as a result of weaving in advice.
            This is an important fact that developers using both aspects and
            serialization should be aware of.  It is likely that a future
            version of the compiler will be better behaved regarding the
            <varname>serialVersionUID</varname>.
          </para>
          <para>However, changes to the <literal>serialVersionUID</literal>
            attribute are typically only important when using serialization for
            the long-term persistence of  objects.  Using standard Java
            serialization for long-term persistence has a number of drawbacks
            and many developers already use alternative solutions.  For one
            possibly standard solution, see
            <ulink url="http://jcp.org/jsr/detail/057.jsp">
              Long-Term Persistence for JavaBeans Specification
            </ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:applets"
            xreflabel="Q:How can I use AspectJ with applets?">
          <para>How can I use AspectJ with applets?</para>
        </question>
        <answer>
          <para>
            Just include the aspectjrt.jar as a required archive.  
            For example, here is the HTML code for an HTML editor 
            applet that contains some debugging aspects:
          </para>
          <programlisting>
            <![CDATA[
<APPLET
   CODE='com.company.swing.applets.EditorApplet'
  WIDTH='700'
 HEIGHT='525'>
    <PARAM NAME="CODE" VALUE="com.company.swing.applets.EditorApplet" >
    <PARAM NAME="ARCHIVE" 
         VALUE ="../company-applets.jar,../aspectjrt.jar,../xmlrpc-applet.jar" >
    <PARAM NAME="type" VALUE="application/x-java-applet;version=1.4">
    <PARAM NAME="scriptable" VALUE="false">
</APPLET>
]]>
          </programlisting>
          <para>
          The above markup has worked reliably with the Java Plugin
          (included in the JRE 1.4.x) in IE 6, Mozilla 1.1 (Win32), 
          and Mozilla 1.0.1 (Red Hat Linux 8.0).  
          The following link describes how to configure Mozilla/Netscape
          6.x/7.x to use the Java Plugin from a JRE/SDK installation:
          <ulink url="http://java.sun.com/j2se/1.4.1/manual_install_linux.html">
          http://java.sun.com/j2se/1.4.1/manual_install_linux.html</ulink>.
          (Thanks to Chris Bartling for this answer.)
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:typeoblivious"
            xreflabel="Q:How can I specify types for advice that captures primitives, void, etc.?">
          <para>How can I specify types for advice that captures primitives, void, etc.?</para>
        </question>
        <answer>
          <para>
	In some cases, AspectJ allows conversion from values of primitive types to Object, 
	so that highly polymorphic advice may be written.  This works if an advice parameter 
	or the return type for around is typed to Object.  So:
          </para>
          <programlisting>
class Test {
    static int i;
    public static void main(String[] args) {
        i = 37;
    }
}

aspect TraceSet {
    before(Object val): set(* Test.*) &amp;&amp; args(val) {
        System.err.println(val);
        System.err.println(val.class);
    }
}
          </programlisting>
          <para>
            will print out
          </para>
          <programlisting>
37
java.lang.Integer
          </programlisting>
          <para>
	For more information, see the Programming Guide
            <ulink url="progguide/semantics-pointcuts.html">
              semantics section "Context Exposure"
            </ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:versioninfo"
            xreflabel="Q:How do I detect which version I am running?">
          <para>How do I detect which version I am running?</para>
        </question>
        <answer>
          <para>The <literal>ajc</literal>
          compiler emits the version when passed the
          <literal>-version</literal> flag as an argument.
          </para>
          <para>To programmatically
          detect the version of the AspectJ runtime while running
          under Java 1.4 or later, get the version from the package:
          <programlisting>
    Package lang = org.aspectj.lang.JoinPoint.class.getPackage();
    String version = lang.getImplementationVersion();
          </programlisting>
          </para>
          <para>When running under Java 1.3 or earlier, read the manifest
          directly.  For example code, see the source for
          <literal>AjBuildManager.checkRtJar(AjBuildConfig)</literal>
          in the <literal>org.aspectj.ajdt.internal.core.builder</literal>
          package of the <literal>org.aspectj.ajdt.core</literal> module,
          available as described in
          <xref linkend="q:buildingsource"/>.
          </para>
          <para>Note that the version of AspectJ for the tools in
          <literal>aspectjtools.jar</literal> is in
          <literal>org.aspectj.bridge.Version</literal>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:synchronizedAdvice"
            xreflabel="Q:How do I write synchronized advice?">
          <para>How do I write synchronized advice?</para>
        </question>
        <answer>
          <para>The only modifier advice can take is <literal>strictfp</literal>.
          However, you can enclose the body of the advice in a synchronized
          clause:
          <programlisting>
before() : pc() {
  synchronized (this) {
    // advice code here
  }
}
          </programlisting>
          </para>
          <para>It should not be necessary to synchronize a percflow aspect,
          but you might do this for perthis, pertarget, or issingleton (default)
          aspects.  To serialize advice in multiple aspects, synchronize on a
          lock object available (only) to the aspects.
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="problems" xreflabel="Common Problems">
      <title>Common Problems</title>
      <qandaentry>
        <question id="q:infiniterecursion"
            xreflabel="Q:When I run, I get a StackOverflowError or no output.">
          <para>When I run, I get a <literal>StackOverflowError</literal>
        (or a long stack trace or no output whatsoever)
          </para>
        </question>
        <answer>
          <para>Most likely this is a case of infinite recursion, 
          where advice is advising itself. It presents as a 
          <literal>StackOverflowError</literal>
          or silence as the VM exhausts itself in the recursion.
          </para>
          <para>Of course, infinite recursion is possible in Java:</para>
          <programlisting>
public class Main {
    public static void main(String[] args) {
        try {
           main(args);
        } finally {
           main(args);
        }
    }
}
          </programlisting>
          <para>If you compile and run this program, and it will fail silently, trying
            to process the finally clause even after throwing the StackOverflowError.
          </para>
          <para>Here's a similar AspectJ program where the recursion is 
          not so obvious:
          </para>
          <programlisting>
aspect A {
    after():  call(* *(..)) { System.out.println("after " + thisJoinPoint); }
}
          </programlisting>
          <para>This re-invokes itself because it advises any call.
          It invokes itself even after an exception is thrown, since
          <literal>after</literal> advice, like a finally clause, runs even 
          after exceptions are thrown. You can fix this by following two practices:
          </para>
          <para>In AspectJ 1.1, the String concatenation operator (+) is
          	advised in its StringBuffer form, so if your advise uses 
          	String + in a way that is picked out by your pointcut,
          	you will get infinite recursion.</para>
          <para>
          (1) Use <literal>after returning</literal> to advise normal completions
              or <literal>after throwing</literal> to advise abrupt completions.
              If you use <literal>after</literal> or <literal>after throwing</literal>, 
              write the advice with the same care you would a finally clause, 
              understanding that it may run after some failure.
          </para>
          <para>(2) Avoid writing advice that advises itself.  One simple way to
          do so is to exclude the code within the current aspect:
          </para>
          <programlisting>
aspect A {
    after() returning:  !within(A) &amp;&amp; call(* *(..)) { 
        System.out.println("after " + thisJoinPoint); 
    }
}
          </programlisting>
          <para>A better way is often to re-write the pointcut.  
          If the advice is advising itself accidentally, that's a sign that 
          the pointcut is not saying what you mean.
          </para>
          <programlisting>
aspect A {
    pointcut withinTargetClasses() : within(A+) || within(B+);
    after() returning:  withinTargetClasses() &amp;&amp; call(* *(..)) { 
        System.out.println("after " + thisJoinPoint); 
    }
}
          </programlisting>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:typelessdeclarations"
            xreflabel="Q:I've declared a field on every class in my package; how do I use it in advice?">
          <para>I've declared a field on every class in
            my package; how do I use it in advice?
          </para>
          <programlisting>
aspect A {
    boolean com.xerox..*.dirtyFlag;
    after (Object target) returning 
        : target(target) &amp;&amp; call(* com.xerox..*.set*(..)) {
        target.dirtyFlag = true; // compile fails here
    }
}
          </programlisting>
        </question>
        <answer>
          <para>You need a type to refer to any member, field or method.
          It's generally better to introduce onto an interface and
          declare classes to implement the interface, which permits you
          to use the interface type in advice formals.
          </para>
          <programlisting>
aspect A {
    interface TrackingSets {}
    boolean TrackingSets.dirtyFlag;
    declare parents : com.xerox..* implements TrackingSets;

    after (TrackingSets target) returning 
        : target(target) &amp;&amp; call(* com.xerox..*.set*(..)) {
        target.dirtyFlag = true; 
    }
}
          </programlisting>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:ajcoom"
            xreflabel="Q:The AspectJ compiler aborts with an OutOfMemoryError when compiling many classes. How can I fix this?">
          <para>The AspectJ compiler aborts with an OutOfMemoryError when
          compiling many classes. How can I fix this?
          </para>
        </question>
        <answer>
          <para><literal>ajc</literal> can use more memory than a javac
           compile of the corresponding pure-java sources when aspects
           are added to the mix.  You'll need to increase the memory
           available.
          </para>
          <para>The command <literal>ajc</literal> is actually a script that
            launches a Java virtual machine with the correct classpath. You
            should make a copy of this script, rename it, and then edit it.
            Change the -Xmx option, size of memory allocation pool (heap). You
            might try <literal>-Xmx128M</literal> or even
            <literal>-Xmx256M</literal>.
          </para>
          <para>When running under Ant, give Ant more memory or
          use the <literal>fork</literal> option together with
          the <literal>Xmaxmem</literal> option.
          </para>
          <para>When running under an IDE, look to the documentation
          for the IDE to determine how to increase available memory.
          </para>
          <para>In either case, doing incremental compilations can hold on to
			  more memory than a one-shot compile process, as the compiler
			  trades space for time in recompiles.
          </para>
        </answer>
      </qandaentry> 
      <qandaentry>
        <question id="q:duplicateclass"
            xreflabel="Q:Why do I get a message that my class is already defined?">
          <para>
            Why do I get a message that my class is already defined?
          </para>
        </question>
        <answer>
          <para>
            Most commonly, a source file was specified twice on the command line
            (e.g., directly and by a *.java entry in a .lst file).
            However, sometimes you have defined a class in two files in the
            same package, and you need to rename the class or change its 
            scope.  You should get this message from any Java compiler.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:ajcrecompile"
            xreflabel="Q:ajc recompiles all files every time. How can I make it recompile only the files that have changed?">
          <para>
            <literal>ajc</literal> recompiles all files every time. 
          How can I make it recompile only the files that have changed?
          </para>
        </question>
        <answer>
          <para>
            <literal>ajc</literal> 1.0 does not support incremental
          compilation, but since 1.1 <literal>ajc</literal> does when passed the 
          	<literal>-incremental</literal> option.  It may still recompile
          files that have not changed, if they could be affected by aspects
          in particular ways, but the files compiled should be fewer
          and result in faster compiles.
          Further, the 1.1 release supports binary weaving, so you
          need not recompile if you already have .class files.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:ajcjvm"
            xreflabel="Q:ajc is using the wrong JVM. How do I fix it?">
          <para>
            <literal>ajc</literal> is using the wrong JVM. How do I
            fix it?
          </para>
        </question>
        <answer>
          <para>The easiest way to fix this is to re-install
            <literal>ajc</literal> (using the same <literal>.class</literal> or
            <literal>.exe</literal> file that you originally downloaded) and
            this time make sure to tell it to use the desired JDK (typically
            the JDK versions 1.2 or 1.3 from Sun).
          </para>
          <para>If you are familiar with DOS batch files or shell programming,
            you could also fix this by simply editing the
            <literal>bin\ajc.bat</literal> or <literal>bin/ajc</literal>
            script.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:idebalkingataspects"
            xreflabel="Q:My IDE is trying to parse AspectJ files which makes my project unusable. What can I do?">
          <para>My IDE is trying to parse AspectJ files which makes my project unusable.
                What can I do?
          </para>
        </question>
        <answer>
          <para>
        When working with an unsupported IDE that objects to the syntax of 
        AspectJ source files (and, e.g., automatically gathers them 
        in a source tree as Java files based on the .java extension), 
        you can use the .aj extension for your AspectJ files.  
        The ajc compiler accepts both .java and .aj files, and you can 
        set up your build scripts to include the correct list of 
        source files.  (You will have to find another editor for
        editing AspectJ files; you can use the ajbrowser to view
        edit your AspectJ files and navigate the crosscutting structure.)
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:idememory"
            xreflabel="Q:I used to be able to compile my program, but now I run out of memory.">
          <para>I used to be able to compile my program in my IDE, but when I
                use AJDE, I run out of memory (or it goes really slow).
          </para>
        </question>
        <answer>
          <para>
        The ajc compiler does more analysis than (e.g.,) javac,
        and AJDE may in some IDE's hold a copy of the structure tree until the
        next tree is available from the compile process.  Both mean that you may
        need extra memory to compile the same program.  However, increasing
        available memory to the point that you are swapping to disk can
        slow the process considerably.
          </para>
          <para>
        If you are having problems and would like to find the optimal memory 
        allocation, iteratively decrease the amount of memory available until 
        AJDE or ajc signals out-of-memory errors, and then increase that 
        amount by 5-10%.
          </para>
          <para>
        To increase memory for the ajc compiler, see <xref linkend="q:ajcoom"/>.
        For your IDE, do something similar or follow the provider's instructions.
        For example, to increase memory in JBuilder, edit the 
        <literal>jbuilderX/bin/jbuilder.config</literal>
        file to have an entry like:
<programlisting>        
vmparam -Xmx384m
</programlisting>        
          </para>
          <para>
        If it turns out that your project is too big to use with AJDE, your IDE 
        may nonetheless support external commands or Ant build processes, which
        run outside the IDE memory space.  For a JBuilder Ant plugin, some
        people have directed us to <ulink url="http://antrunner.sourceforge.net"/>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:noaspectbound"
            xreflabel="Q:When I run, I get a NoAspectBoundException or a
            ClassNotFound message for NoAspectBoundException.">
          <para>
            When I run, I get a <literal>NoAspectBoundException</literal> or a
            ClassNotFound message for <literal>NoAspectBoundException</literal>.
          </para>
        </question>
        <answer>
        	<para>This happens when an aspect is not associated with an object
        		that is being advised.  We have seen this happen two ways:
			  <itemizedlist>
				<listitem>
				  <para>You get a ClassNotFound message for 
				  	<literal>NoAspectBoundException</literal> when loading a 
				  	class affected by aspects if <literal>aspectjrt.jar</literal> 
				  	classes are not on the runtime classpath.   
        			To fix this, put the classes on the classpath.
				  </para>
				</listitem>
				<listitem>
				  <para>
				  	You can get a <literal>NoAspectBoundException</literal> when
				  	there is a cycle in aspect initialization or static 
				  	initialization, most commonly when an aspect advises
				  	its own initializer.  To fix this, first find the class that
				  	fails to load by running java in debug mode or looking 
				  	at the <literal>NoAspectBoundException</literal> trace, 
				  	and then fix the offending (probably unintended) dependency.
				  	Most often, it comes from a pointcut like
				  	<literal>staticinitialization(com.company..*)</literal>
				  	or <literal>within(com.company..*)</literal>, which
				  	can include any aspects in the same subpackages.
				  	You can avoid advising most join points associated with
				 	the aspect <literal>TheAspect</literal>
				  	by adding <literal>&amp;&amp; !within(TheAspect)</literal>
				  	to your pointcut.
				  </para>
				</listitem>
			  </itemizedlist>
          </para> 
        </answer>
      </qandaentry>
		
      <qandaentry>
        <question id="q:stacktraces"
            xreflabel="Q:My stack traces don't make sense.  What gives?">
          <para>
            My stack traces don't make sense.  What gives?
          </para>
        </question>
        <answer>
          <para>In 1.0, unless you are using the <literal>ajdb</literal> debugger, 
          stack traces may
          have synthetic methods in the stack, and the line numbers may
          not track your source code.  The 
            <ulink url="devguide/index.html">
              Development Environment Guide</ulink>
          discusses how to interpret stack at the end of the
            <ulink url="devguide/ajc-ref.html">
              Reference for ajc</ulink>.
          </para>
          <para>In 1.1, line numbers should work correctly.
          The only difference from a normal stack might be the addition
          of extra stack frames for call-backs.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:advicenotrunning"
            xreflabel="Q:My advice is not running (or running twice), and I don't know why.">
          <para>
            My advice is not running (or running twice), and I don't know why.
          </para>
        </question>
        <answer>
          <para>
          	When advice is not running,   
          	there is probably a problem in the pointcut.
          Sometimes users specify pointcuts that 
          do not mean what they intend -
	      most often when they misspell a type name. Run the compiler in
	      <literal>-Xlint</literal> mode, which will flag some likely mistakes,
	      like the type name.  
          If that does not work, and your pointcut is staticly-determinable,
          use a declare statement to identify affected code.  (For more 
          information, see <xref linkend="q:knowWhenAspectsAffectClasses"/>.)
          If that does not work and your pointcut is dynamically determined, 
          see if your join points are executing at all by using
              TraceJoinPoints.java from <xref linkend="q:seeingjoinpoints"/>.
          </para>
          <para>When advice is running more than it should, either
          	(1) your advice is in an abstract aspect and the pointcut picks
          	out the same join point for more than one concrete instantiation
          	of the aspect, or
          	(2) your pointcut picks out more join points than you intend.
          </para>
          <para>
          In the case of advice in abstract aspects, the advice will run once
          for each concrete instance of the aspect. 
          If the pointcut for that advice picks out the same join point for two 
          concrete aspects, then the correct behavior is for the advice to run 
          the advice twice at that join point.
          </para>
          <para>
          To see if your pointcut picks out the join points you intend, you
          can use IDE support, logging, or declare-warnings.
          If you are using IDE support, you should be able to trace back from
          the pointcut or advice to the join points which can be statically
          determined to be affected.  
          Without IDE support, you can write
          declare-warning statements to identify code affected by staticly-
          determinable pointcuts.
          To identify advised dynamic join points,
          you can try using <literal>TraceJoinPoints.java</literal> as above, 
          or update the advice to print the source location of the join point.  
          Doing any of these should show if the advice applies to code that 
          you did not expect.
          </para>                
          <para>If you've done this and convinced yourself it's not working,
          it may be a bug.  See <xref linkend="q:bugreports"/>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:adviceOnOveriddenMethods"
            xreflabel="Q:My advice runs for each overridden method!">
          <para>
            My advice runs for each overridden method!
            </para>
        </question>
        <answer>
           <para>Most likely you are advising the method execution join
           	point and specifying the defining signature.
           	Since all overriding methods share this signature,
           	the advice runs for each method executed.
           	(This happens, e.g., when one method invokes the same method  
           	in the superclass using <literal>super.{method}(..)</literal>).
           	This is the correct behavior.
          </para>
          <para>To avoid this, use the <literal>call(..)</literal> pointcut
          	designator, or use <literal>!cflow(..)</literal> to pick
          	out only the initial method-execution.
          </para>
        </answer>
      </qandaentry> 
      <qandaentry>
        <question id="q:tejpsp"
            xreflabel="Q:I don't understand when thisEnclosingJoinPointStaticPart is available.">
          <para>
            I don't understand when thisEnclosingJoinPointStaticPart is available.
          </para>
        </question>
        <answer>
          <para>
          	<literal>thisEnclosingJoinPointStaticPart</literal> is a special 
          	variable available in the context of advice to refer to the
          	join point, if any, lexically enclosing the current join point:
          	<table>
          		<title>thisEnclosingJoinPointStaticPart</title>
          		<tgroup cols="2">
          			<tbody>
          				<row>
          				<entry>One of these...</entry>
          				<entry>will be tEJSP for each of these:</entry>
          				</row>
          				<row>
          				<entry>
						constructor-execution, method-execution, 
						advice execution, initialization,
  						pre-initialization, static initialization
          				</entry>
          				<entry>
 						constructor-call, method-call, handler, 
 						field-set, field-get
       					</entry>
          				</row>
          			</tbody>
          		</tgroup>	
          	</table>
			Expressions in the body of handlers have the same
  			<literal>thisEnclosingJoinPointStaticPart</literal>
  			as the handler itself.
          </para>
        </answer>
      </qandaentry> 
      <qandaentry>
        <question id="q:packagedeclares"
            xreflabel="Q:I declared a member on a class with package access, but other classes in the package cannot see it.">
          <para>
            I declared a member on a class with package access, but other classes in the package cannot see it.
          </para>
        </question>
        <answer>
          <para>When declaring parents on other types from an aspect, package access only
	applies to code the implementation controls.  For AspectJ 1.0, that is the set of files
	passed to the compiler.  That means other classes not compiled with the aspect will not
	be able to access the aspect-declared members even if they are in the same package.
	The only way for classes outside the control of the implementation to access aspect-declared
	members is to declare them public.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:interfaceDeclarations"
            xreflabel="Q:I declared a member on a interface, but javac does not see it.">
          <para>I declared a member on a interface, but javac does not see it.
          </para>
        </question>
      
        <answer>
          <para>
          	You have to compile all the top-level implementating
          	classes of the interface using <literal>ajc</literal>.
            From an email by Jim Hugunin on the requirements for AspectJ 1.1 to 
            implement members declared by an aspect on an interface:
          </para>
          <para>
            If you introduce non-static fields or non-abstract methods on an interface 
            from an aspect, then all of the top-most implementors of that interface must 
            be woven by that same aspect.  
            (A class C is a top-most implementor of an interface I if C implements I 
            and the superclass of C does not implement I.)
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:cantfindjavac"
            xreflabel="Q:ajc 1.0 complains that it can't find javac. What's wrong?">
          <para>
            <literal>ajc</literal> 1.0 complains that it can't find
            <literal>javac</literal>. What's wrong?
          </para>
        </question>
        <answer>
          <para>
            <literal>ajc</literal> 1.0 does not try to locate
            <literal>javac</literal> in your path: it uses the
            <literal>javac</literal> classes directly. In JDK 1.2 and 1.3 these
            classes are found in <literal>tools.jar</literal> (in the
            <literal>lib</literal> directory of the JDK distribution), which
            must be on your classpath to make
            <literal>ajc</literal> work with <literal>javac</literal>. 
            Inspect the java command that launches ajc to make sure that 
            <literal>tools.jar</literal> is on the classpath for ajc;
            the -classpath option only applies to the sources compiled.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:ajdocneeds13"
            xreflabel="Q:I'm running under 1.4, but ajdoc asks for 1.3 (or throws IllegalAccessError for HtmlWriter.configuration)">
          <para>
          I'm running under 1.4, but <literal>ajdoc</literal> asks for 1.3 
          (or throws IllegalAccessError for HtmlWriter.configuration)
          </para>
        </question>
        <answer>
          <para>
          The 1.0 implementation of <literal>ajdoc</literal> uses
	      specific javadoc classes in the J2SE 1.3 tools.jar.
	      We are working on addressing this limitation, but in the interim
	      it is best to run ajdoc under 1.3.
          </para>
          <para>
          When running from the command-line scripts, edit the scripts directly
          to put the 1.3 tools.jar first on the classpath.  (The installer does
          not know about this limitation of ajdoc.)
          </para>
          <para>
          When running from Ant, users often have tools.jar in ${ant.classpath}
          (to make javac, et al work).  That makes it impossible to run the ajdoc
          taskdef (which does not currently support forking), so you'll need to
          run a separate ant process, either from the command-line or via Ant's
          exec task (the Ant task will propagate the classpath).  
          If the wrong tools.jar is not on the ant classpath, then it should work
          to put the 1.3 tools.jar in the taskdef classpath.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:compileunits"
            xreflabel="Q:I set up different files to my compiles to change what the aspects see, but now I don't understand how the aspects are working?">
          <para>I set up different files to my compiles to change what
                the aspects see, but now I don't
	        understand how the aspects are working.
          </para>
        </question>
        <answer>
          <para>It is a bad practice to use the compilation unit
	   to control crosscutting.  Aspects and pointcuts especially
            should be written to specify crosscutting precisely.	
            Aspects will behave the same when you add files if
            you initially included all files affected by your aspects.
            If you use the compilation unit, then your code will behave
	    differently in AspectJ implementations that do not limit 
	    themselves to specified files.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:readingpreprocessedcode"
            xreflabel="Q:I'm reading the code generated by ajc 1.0 in -preprocess mode, and it seems like it would not work.">
          <para>I'm reading the code generated by <literal>ajc</literal> 1.0
        in <literal>-preprocess</literal> mode, and it seems like it would not
        work (or "like it works this way").
          </para>
        </question>
        <answer>
          <para>The generated code can be difficult for a human to read and
          understand.  The compiler uses implementation techniques which might
          not be apparent.  To determine if the code is behaving correctly, you
          should write and run a program that attempts to provoke the error you
          suspect.  Similarly, you should not rely on invariants you infer from
          the generated code (especially naming conventions for generated members).
          Please rely only on the semantics stated in the appendix of the
          AspectJ <ulink url="progguide/index.html">Programming Guide</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:injection"
            xreflabel="Q:I've heard AspectJ can generate or inject code into my code.  Is this true?">
          <para>I've heard AspectJ can generate or inject code into my code.  
	        Is this true?
          </para>
        </question>
        <answer>
          <para>
            This is a misconception spawned from the early implementation.
          </para>
          <para>
	  AspectJ does not "inject" or "generate" code.  In AspectJ the
	  pointcut constructs allow the programmer to identify join points,
	  and the advice constructs define additional code to run at those
	  join points.
          </para>
          <para>
	  So the semantic model of advice is like the semantic model of a 
	  method -- it says "when any of these things happen, do this".
          </para>
          <para>
	  People who worked with earlier versions of AspectJ, in which ajc
	  was very explicitly a pre-processor, sometimes thought of AspectJ
	  as injecting code.  But that was an artifact of the implementation,
	  not the underlying language semantics.
          </para>
          <para>
	  This distinction is important for two reasons.  One is that thinking
          about it this way will make more sense at the implementation continues
          to evolve towards load-time or runtime weaving.  The other is that
          it makes it much easier to understand the semantics of advice on
          cflow pointcuts.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:newjoinpoints"
            xreflabel="Q:Why can't AspectJ pick out local variables (or array elements or ...)?">
          <para>Why can't AspectJ pick out local variables (or array elements or ...)?
          </para>
        </question>
        <answer>
          <para>Users have sometimes wanted AspectJ to pick out 
          	many more join points, including
          	<itemizedlist>
          		<listitem><para>method-local field access</para></listitem>	
          		<listitem><para>array-element access</para></listitem>
          		<listitem><para>loop iteration</para></listitem>
          		<listitem><para>method parameter evaluation</para></listitem>
          	</itemizedlist>
          	Most of these have turned out not to make sense,
          	for a variety of reasons:
          	<itemizedlist>
          		<listitem><para>it is not a commonly-understood unit for Java programmers</para></listitem>
          		<listitem><para>there are very few use-cases for advice on the join point</para></listitem>
          		<listitem><para>a seemingly-insignificant change to the underlying program
          			      causes a change in the join point</para></listitem>
          		<listitem><para>pointcuts can't really distinguish the join point in question</para></listitem>	
          		<listitem><para>the join point would differ too much for different 
          			implementations of AspectJ, or would only be implementable
          			in one way
          			</para></listitem>
          	</itemizedlist>
          	We prefer to be very conservative in the join point model for the language,
          	so a new join point would have to be useful, sensible, and implementable.
          	The most promising of the new join points proposed are for exception
          	throws clauses and for synchronized blocks.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:reflectiveCalls"
            xreflabel="Q:Why doesn't AspectJ pick out reflective calls?">
          <para>Why doesn't AspectJ pick out reflective calls?
			  The pointcut <literal>call(void run())</literal> 
			  won't pick out a call using reflection, like
			  <literal>((Method)run).invoke(null, args)</literal>.
          </para>
        </question>
        <answer>
          <para>The pointcut 
			  <literal>execution(void run())</literal> will
			  work. The call pointcut doesn't work because 
			  <literal>Method.invoke(..)</literal> is the Java method-call,
			  and AspectJ cannot delve into the Java reflection library to
			  implement call semantics.  To advise a reflective call
			  (e.g., because the compiler does not control the code for the
			  method execution), test the context for <literal>invoke(..)</literal>.
			  Here's a pointcut that tests only if the method name is
			  correct:
          </para>
          <programlisting>
aspect A {
    pointcut runReflectiveCall(Method run) : target(run) &amp;&amp;
         call(Object Method.invoke(..)) &amp;&amp; if("run".equals(run.getName()));		  
    before() : runReflectiveCall(Method) { 
        System.out.println("before reflective call " + thisJoinPoint); 
    }
}
          </programlisting>
			        </answer>
      </qandaentry>
	  <qandaentry>
        <question id="q:currentbugs"
            xreflabel="Q:What are the bugs now most affecting users?">
          <para>What are the bugs now most affecting users?</para>
        </question>
        <answer>
		  <para>The bugs affecting the semantics of the language
			  are marked with the "info" keyword.  Find them with
			  the query
			  <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&amp;keywords=info">
						  http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&amp;keywords=info
						  </ulink>
		  </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:runtimeMemory"
            xreflabel="Q:What extra memory is required at runtime?">
          <para>What extra memory is required at runtime?
          </para>
        </question>
        <answer>
          <para>When running classes produced by the AspectJ weaver or compiler,
              there are no significant hidden uses of memory.  As would be expected,
              each aspect is instantiated.  The per-object aspects (like
              <literal>pertarget</literal> or <literal>perthis</literal>)  
			  in some implementations
              use a map to link aspects and the associated object.  When using
              <literal>cflow</literal>-related pointcuts, a <literal>ThreadLocal</literal>
              is used to track control flow for each affected thread.
		  </para>
		  <para>Of course, the size and code in an aspect can require memory.
			  Aside from normal Java practices, take care with join point references.
              When referencing the static part of a join point (e.g., 
              <literal>thisJoinPointStaticPart</literal>), only one object is
              created.  However, if you reference the join point itself
              (e.g., <literal>thisJoinPoint</literal>), then one 
              <literal>JoinPoint</literal> object will be created for each 
              join point running advice.
		  </para>
		  <para>Aspect instances will be garbage collected just like regular objects 
			  after there are no more strong references to them.  For the default
			  aspect instantiation model, <literal>issingleton</literal>, the aspect
			  class retains a reference to the singleton instance, in order to 
			  implement <literal>static {AspectClass} aspectOf()</literal>, so 
			  singleton instances will not be garbage collected until the class is.
			  For long-running or memory-critical programs, consider using weak 
			  references in singleton aspects for state that should be garbage collected.
		  </para>
		  <para>Finally, when using load-time weaving, the weaver can require
              memory in its own right.  Because the class loader never can 
              know when it is done loading classes, the weaver can hold on
              to the aspects required to weave for some time.  There are 
              strategies for minimizing this (with different trade-off's),
              so the time and memory required for load-time weaving will
              vary as load-time weaving evolves.
		  </para>
        </answer>
      </qandaentry>
       <qandaentry>
        <question id="q:weavingcglib"
            xreflabel="Q:I get a VerifyError when running CGLIB generated code that has been woven by AspectJ. Why is this?">
          <para>I get a VerifyError when running CGLIB generated code that has been woven by
          AspectJ. Why is this?
          </para>
        </question>
        <answer>
          <para>When weaving after advice into any piece of code, the AspectJ strategy is to make all
          exit points from that code jump to a single exit point that executes the advice
          before returning.  There is a verifier rule in the JVM specification that specifies
          that all routes to a jump destination must have the same height stack when they get there,
          regardless of the route taken to get there through the bytecode.  The CGLIB generated code has different
          stack heights at the various exit points.  This is not a problem with the CGLIB generated code,
          it is perfectly valid - it is just unusual and the AspectJ weaving strategy causes the
          verify error to trigger when it makes all exits jump to a single destination.
          </para>
          <para>AspectJ could cope with this and instead implement after advice by calling the
          advice and returning at each exit point.  However, it is unlikely that the user
          actually meant to weave the CGLIB generated code in the first place - and so usually
          the right thing to do is to exclude CGLIB generate code from the weaving process by
          appropriate use of the exclude element in the aop.xml.  A typical clause in the aop.xml might
          look as follows:
          </para>
           <programlisting>
&lt;weaver&gt;
  &lt;exclude within="*CGLIB*" /&gt; 
&lt;/weaver&gt;
          </programlisting>
        </answer>
      </qandaentry> 
    </qandadiv>

    <qandadiv id="aj11" xreflabel="AspectJ 1.1 and eclipse.org">
      <title>AspectJ 1.1 and eclipse.org</title>
      <qandaentry>
        <question id="q:whyeclipse"
            xreflabel="Q:Why did the AspectJ project move to eclipse.org?">
          <para>Why did the AspectJ project move to eclipse.org?
          </para>
        </question>
        <answer>
          <para>From the message sent to users:
          </para>
          <para>
            AspectJ has come a long way -- the language has
            stabilized; there are a rapidly growing number of
            commercial users; the 1.1 release is imminent and will
            include byte-code weaving and incremental compilation;
            and the tool support is now well integrated with several
            major IDEs. 
          </para>
          <para>
            This growth of the community and the technology means
            that the original research and prototype development of
            AspectJ is complete. As such it is time for ongoing
            development and support of AspectJ to move outside of
            PARC. This has already started to happen; the Eclipse
            AJDT plug-in and the several books in preparation are
            examples. 
          </para>
          <para>
            To encourage the growth of the AspectJ technology and
            community, PARC is transferring AspectJ to an
            openly-developed eclipse.org project. This project will
            include documentation, web site, mailing lists, bug
            database, and sources for the compiler. The
            command-line AspectJ compiler is still the primary tool
            produced by this project, in addition to APIs that support
            integration with a variety of IDEs. The Eclipse plug-in will
            remain at eclipse.org, while the NetBeans, JBuilder and
            Emacs support will move to SourceForge.net projects.
            We look forward to your involvement with and
            contribution to those projects. 
          </para>
          <para>
            We see Eclipse as an excellent new home for core
            AspectJ technology development -- it is an active
            community of Open Source development and innovation
            in the Java space. Once development moves to
            Eclipse.org, others will be able to contribute more easily.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:eclipserequired"
            xreflabel="Q:Do I have to download Eclipse to use AspectJ?">
          <para>Do I have to download Eclipse to use AspectJ?
          </para>
        </question>
        <answer>
          <para>No.  The AspectJ tools download is completely self-contained
                and does not require that you work in Eclipse.
                For information on IDE support, see
                 <xref linkend="q:integrateWithDevTools"/>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:eclipseetc"
            xreflabel="Q:What are the relationships between AspectJ, JDT, 
                Eclipse, AJDT, and IDE support generally?">
          <para>What are the relationships between AspectJ, JDT, 
                Eclipse, AJDT, and IDE support generally?
          </para>
        </question>
        <answer>
          <para>Eclipse is a software platform.
          </para>
          <para>JDT is an eclipse project to support Java development.  
			JDT has a Java compiler.
          </para>
		  <para>AspectJ 1.1 is built on Eclipse/JDT's Java compiler
                but is distributed standalone and can run standalone.
                With the AspectJ distribution, you can compile and run
                AspectJ programs and use the AspectJ structure browser.
          </para>
		  <para>AJDT is an eclipse project to integrate AspectJ 
		  into Eclipse/JDT so you can use Eclipse to develop 
		  AspectJ programs.  AJDT aims to support the full Eclipse
		  experience - searching, compiler-error tasks, etc.
		  AJDT will use the AspectJ Development Environment (AJDE)
		  API's for creating IDE integrations, as well as hooking
		  in to the model underlying the Java compiler.
          </para>
          <para>Similarly, Sourceforge has projects integrating 
          AspectJ into other development environments
          using the AJDE API's: 
          <ulink url="http://aspectj4emacs.sourceforge.net">
              AspectJ for Emacs</ulink>, 
          <ulink url="http://aspectj4jbuildr.sourceforge.net">
              AspectJ for JBuilder</ulink>, and 
          <ulink url="http://aspectj4netbean.sourceforge.net">
              AspectJ for NetBeans</ulink>.
          </para>
          <para>This is the right level of separation/integration.  
          AspectJ is available standalone, leverages an existing open-source
          compliant Java compiler, and supports external projects 
          doing IDE integrations in Eclipse, Emacs, JBuilder, and NetBeans
          through a common API, AJDE.
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="AspectJ5" xreflabel="AspectJ 5 and Java 5">
     <title>AspectJ 5 and Java 5</title>
      <qandaentry>
        <question id="q:aspectj5features"
            xreflabel="Q:What are the new features of AspectJ 5?">
          <para>
            What are the new features of AspectJ 5?
          </para>
        </question>
        <answer>
            <para>
                All the new features are documented in the 
                <ulink url="adk15notebook/index.html">
              AspectJ 5 Developer's Notebook</ulink>
                and the 
                <ulink url="devguide/index.html">
              AspectJ Development Environment Guide</ulink>.
                To summarize:
            </para>
			<itemizedlist>
				<listitem><para>
                    Java 5 support: as an extension to Java, AspectJ supports
                    all the new language features of Java 5, including generics
                    (parameterized types), autoboxing, covariant return types,
                    enhanced for-loops, enums, varargs, and of course 
                    annotations.
				</para></listitem>
				<listitem><para>
                    Java 5 extensions: the AspectJ language has been extended
                    to make use of Java 5 language features.
                    <itemizedlist>
                        <listitem><para>
                            Generic aspects: an abstract aspect can be declared
                            with a generic type parameter which can be used 
                            in pointcuts and when declaring members on the aspect
                            (but not when declaring members on other types).
        				</para></listitem>
                        <listitem><para>
                            Annotations: pointcuts can now pick out join points
                            based on the associated annotations, annotation
                            values can be bound in the same way that other
                            context variables are bound at the join point,
                            and annotations may be declared on other types in
                            an aspect.
        				</para></listitem>
                    </itemizedlist>                    
				</para></listitem>
				<listitem><para>
                    Annotation-style aspects: AspectJ 5 integrates AspectWerkz-style
                    aspects declared in annotations.  This permits aspects to 
                    be written and compiled in pure-java code and woven using
                    build-time or load-time weaving with the AspectJ weaver.
                    (The original AspectJ language aspects are distinguished
                    as "code-style" aspects.)
				</para></listitem>
				<listitem><para>
                    AspectWerkz load-time weaving: Load-time weaving is
                    greatly improved for all versions of Java, and now supports
                    an XML configuration file which can declare concrete aspects.
                    This means developers can deploy binary abstract aspects
                    that deployers configure using only XML.
				</para></listitem>
				<listitem><para>
                    pertypewithin instantiation model: aspects may now be instantiated
                    on a per-class basis.
				</para></listitem>
				<listitem><para>
                    Reflection and runtime support: AspectJ 5 supports reflection
                    on aspects using the Aspect class, and also support runtime
                    evaluation of pointcuts using a pointcut parser.
				</para></listitem>
			</itemizedlist>
          <para>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:codeversusannotationstyles"
            xreflabel="Q:Should I use code- or annotation-style aspects?">
          <para>
            Should I use code- or annotation-style aspects?
          </para>
        </question>
        <answer>
          <para>
            To use AspectJ, you can use the original code-style aspects
            or the annotation-style aspects new in AspectJ 5.  
          </para>
          <para>
            The original code-style is a small extension of the Java language
            designed to express crosscutting as clearly as possible
            in ways familiar to most Java programmers.
            To use the original code-style aspects,
            compile them with the AspectJ compiler or weave
            pre-compiled binary aspects using the AspectJ binary (.class)
            weaver, either at build-time or at class-load-time.
            Code-style aspects have excellent IDE support, allowing
            you to navigate to and from affected source code.
          </para>
          <para>
            Annotation-style
            aspects are written (not surprisingly) using annotations.
            They use the subset of the AspectJ language that works
            when aspects are woven after the code is compiled.
            The source files are compiled with Javac, which simply saves the 
            annotations in the .class files.  The resulting .class files
              must be woven using
            the AspectJ weaver, which reads the annotations from the
            .class file and uses them to define aspects.
            Annotation-style aspects have the benefit of being compilable
              by Javac, but you can't use the full AspectJ language,
              and you don't enjoy the same level of IDE support
              for viewing crosscutting structure.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:aspectj5ltw"
            xreflabel="Q:What's new about the load-time weaving support in AspectJ 5?">
          <para>
            What's new about the load-time weaving support in AspectJ 5?
          </para>
        </question>
        <answer>
          <para>
              While the AspectJ weaver could be used at load-time in previous
              releases, the AspectJ 5 release supports much better integration
              with the Java 5 VM and the BEA JRocket JVM.  It also supports
              an XML file for configuration that allows deployers to declare
              concrete aspects using only XML.  This means aspect developers
              can write abstract aspects, and deployers need only configure
              <literal>aop.xml</literal> and run using the AspectJ weaver in Java 5.  
              For example, to run Java 5 VM with load-time weaving,
          </para>
<programlisting>
            <![CDATA[
java -javaagent:aspectjweaver.jar -classpath "aspects.jar:${CLASSPATH}" ..
]]>
          </programlisting>        
          <para>
              To declare a concrete aspect, add a a 
              concrete-aspect XML entity to <literal>META-INF/aop.xml</literal>.
              This example extends a tracing aspect to apply to 
              every type in the application:
          </para>
<programlisting>
            <![CDATA[
<concrete-aspect 
    name="com.company.tracing.ConcreteTracing"
    extends="tracing.AbstractTracing">
    <pointcut 
        name="tracingScope" 
        expression="within(com.company.app..*)"/>
</concrete-aspect>                
]]>
          </programlisting>  
            <para>
                For more information, see the
                <ulink url="devguide/index.html">
              AspectJ Development Environment Guide</ulink>.
            </para>      
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="Technology" xreflabel="Understanding AspectJ Technology">
      <title>Understanding AspectJ Technology</title>
      <qandaentry>
        <question id="q:implementation"
            xreflabel="Q:Do I need to know how the compiler works?">
          <para>Do I need to know how the compiler or weaver works?
          </para>
        </question>
        <answer>
          <para>Writing AspectJ programs only requires understanding the
          <ulink url="progguide/index.html">Programming Guide</ulink>.
          However, current implementations do not control everything in
          a system, so AspectJ program semantics may be limited to code
          the implementation controls.  For our implementation, these 
          limitations are stated in 
          <ulink url="progguide/implementation.html">
             Programming Guide Appendix:  Implementation Notes</ulink>.
		  Aside from understanding the use and limitations of the 
		  implementation, there is no need to understand the underlying 
		  technology when writing AspectJ programs.
          </para>
          <para>
          The technology that implements AspectJ interests 
          some academic researchers and some developers 
          who want new features or new ways to weave.
          These extensions are not discussed in the documentation.
          Some are being developed already,
          others are on the drawing board (or perhaps were left off
          long ago), and still others haven't been considered.
		  If you are interested in a certain extension, 
          check the bug database for feature requests
          and the mailing list archives for any past discussions.
		  Then email the list to see if it's been considered. 
		  For more information, see
		      <xref linkend="Developers"/>.     
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:whitepapers"
            xreflabel="Q:How does the compiler/weaver work? Are there any white papers?">
          <para>How does the compiler/weaver work? Are there any white papers?
          </para>
        </question>
        <answer>
          <para>
          There are currently no documents describing this process in detail.  
          You can compile programs and inspect the generated source or bytecode,
          or view the source code (see <xref linkend="Developers"/>).
          We hope to write papers on the bytecode weaving model used in 
          AspectJ-1.1 if we can find the time.
          Erik Hilsdale and Jim Hugunin did draft a paper for AOSD 2004,
          now available on Jim's web site:
          <ulink url="http://hugunin.net/papers.html">
          	http://hugunin.net/papers.html</ulink>
          Jim summarized advice weaving in the AspectJ 1.1 implementation in the
          <ulink url="http://dev.eclipse.org/mhonarc/lists/aspectj-dev/msg00519.html">
          	following mailing-list reply</ulink>:
          </para>
          <para>
			Each piece of advice in an aspect is associated with a pointcut.  
			This pointcut is stored in an attribute on the methods 
			corresponding to each piece of advice.  
			Before weaving, all of these pieces of advice are gathered 
			into one large list.
          </para>
          <para>
			Each .class file is woven independently.  
			A .class file is woven by the following steps:
			<itemizedlist>
				<listitem><para>
					Collect all of the joinpoint shadows in the .class file.  
					For every dynamic joinpoint in the AspectJ language model, 
					there is a corresponding static shadow of that joinpoint 
					in the bytecode.  
					For example, every method call joinpoint has an INVOKE 
					bytecode as its static shadow.  Some joinpoints 
					(such as initialization) have much more 
					complicated static shadows.
				</para></listitem>
				<listitem><para>
					Each piece of advice is matched to each static shadow.  
					There are three results possible from this match.
					<itemizedlist>
						<listitem><para>
							Never matches,
							in which case nothing is done to the shadow
						</para></listitem>
						<listitem><para>
							Always matches, 
							in which case the advice is woven into this joinpoint shadow
						</para></listitem>
						<listitem><para>
							Sometimes matches,
							in which case the advice is woven into the shadow 
							along with the minimal dynamic tests to determine 
							if any particular joinpoint in the actual running 
							program matches the advice. 
							The simplest example of sometimes matches is 
							when the pointcut uses if(test()).
						</para></listitem>						
					</itemizedlist>
				</para></listitem>
				<listitem><para>
					If any advice matched any static shadows in the .class file, 
					then the transformed .class file is written out, 
					otherwise it is left unchanged.
				</para></listitem>
			</itemizedlist>
		See <literal>BcelClassWeaver</literal> and 
		<literal>BcelShadow</literal> in the
		<literal>org.aspectj.weaver.bcel</literal> package
		for the two primary classes involved in this process.

		</para>
		<para>
			Note: This explanation ignores the implementations of inter-type 
			declarations completely.  
			It also ignores performance optimizations such as fast-match 
			or pipelining that speed up the process.
		</para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:ltwAppServers"
            xreflabel="Q:How do I get load-time weaving to work in my chosen application server?">
          <para>How do I get load-time weaving to work in my chosen application server?
          </para>
        </question>
        <answer>
          <para>You have two choices based on how wide you want the weaving to take effect: application-server wide and application-specific weaving. 
          You choose between the two by loading aspect artifacts--aspects, associated types, and aop.xml--through the right classloader. 
          The aop.xml must be in the META-INF directory on the classpath for the chosen classloader. In either case, you modify the 
          startup script to specify the -javaagent:path-to/aspectjweaver.jar option to the Java virtual machine. Note that it is not 
          essential that all the artifacts be placed in a single jar.  
          </para>
          <para>For application-server wide weaving, you make aspect artifacts accessible to the server's classloader. Typically, you 
          achieve such access by putting these artifacts in the server's lib directory. For example, for Tomcat, you will place 
          the aspect artifacts in the TOMCAT_HOME/lib directory.</para>
		  <para>For application-specific weaving, you make aspect artifacts accessible to application classloader by bundling 
		  them along with application's classes. For example, for a web application, you will place the aspect artifacts in 
		  the MY_APP/WEB-INF/lib and/or MY_APP/WEB-INF/classes directory.</para>
	      <para>
		  We recommend that you start with application-specific weaving.
          Note that you have an additional option if your application is based on the Spring framework. If you deploy in one of 
          the supported web servers or application servers, you can avoid modifications to the startup script. Please 
          see <ulink url="http://static.springframework.org/spring/docs/2.5.x/reference/aop.html#aop-aj-ltw-spring">http://static.springframework.org/spring/docs/2.5.x/reference/aop.html#aop-aj-ltw-spring</ulink> for more details.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:reflection"
            xreflabel="Q:Does AspectJ use reflection at runtime?">
          <para>Does AspectJ use reflection at runtime?
          </para>
        </question>
        <answer>
          <para>
          The only time that reflection is used during run-time is when the special 
          thisJoinPoint object is used to discover reflective information about the 
          join point.  If you don't use thisJoinPoint then no reflection will be used.
          </para> 
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:loadtimeWeaving"
            xreflabel="Q:What about load-time weaving? Can I weave aspects at runtime?">
          <para>What about load-time weaving? Can I weave aspects at runtime?
          </para>
        </question>
        <answer>
          <para>
          Since the 1.1 release, AspectJ can weave binary aspects
          into classes in bytecode form.  Hooked up to a class loader,
          this can weave class bytecodes after they are read in,
          before the
          class is defined by the VM.  (This means load-time weaving
          only works were aspects are not required to compile the pure-java
          classes.  If the aspects are required, then the Java classes
          have to be compiled with the aspects using the AspectJ compiler.)
              The AspectJ 1.2 release had the
              WeavingURLClassLoader, and the 1.2.1 release introduced
              the aj.bat script for Java 1.4.
              The AspectJ 5 release introduces much better support for
              load-time weaving, including declaring concrete aspects
              in XML files and integrating with Java 5 and BEA JRocket
              JVM's.  See <xref linkend="q:aspectj5ltw"/>.
          </para> 
          <para>Some have asked about only weaving particular classes 
          specified at run-time.
		  Aspects should work across an entire namespace, and problems 
		  will likely result from weaving
          some classes but not others.  Also, it's confusing to 
          specify crosscutting both in the aspect and in the
          list of runtime classes; the crosscutting specification
          should be in the aspect itself,
          where it can be processed by tools.
          </para> 
          <para>And just to state the obvious:
          do not use bytecode weaving, at load-time or otherwise,
          to modify .class files protected by license,
          without permission from the licensor.
          </para> 
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="Developers" xreflabel="AspectJ Project Development">
      <title>AspectJ Project Development</title>
      <qandaentry>
        <question id="q:howitworks"
            xreflabel="Q:I'm interested in the code implementing AspectJ.">
          <para>I'm interested in the code implementing AspectJ.
          </para>
        </question>
        <answer>
          <para>Most people do not need to see the code for AspectJ;
          they can download the binary distribution for documentation
          and tools for writing AspectJ programs.
          </para>
          <para>For people who want to know how the AspectJ technology works,
          the source code is the best resource, until we write some 
          proper white papers
          (see <xref linkend="q:implementation"/>).
		  To get and compile the Java source code for the AspectJ 
          distribution, see
                 <xref linkend="q:buildingsource"/>.
		  </para>
		  <para>Bear in mind when looking at the code that there are many
		  ways to implement the AspectJ language, and the code inspected
		  might be an initial version of a new architecture (e.g., bytecode
		  weaving).
		  </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:contributions"
            xreflabel="Q:How can I get involved with developing the AspectJ project?">
          <para>How can I get involved with developing the AspectJ project?
          </para>
        </question>
        <answer>
          <para>For those who want to contribute to the project,
          here's a general list of ways to do so, in no particular order:
          <itemizedlist>
            <listitem>
              <para>Participate effectively in the mailing lists.
                 The quality of the mailing lists makes a huge difference
                 in the ability of new and experienced AspectJ users
                 to write good code.  For guidance on effective
                 participation, see
                 <xref linkend="q:talktousers"/> and
                 <xref linkend="q:writingbugsandemails"/>.
                 Also, the time that experienced users take in answering emails
                 can directly translate to time developers can use (instead)
                 for fixing bugs or adding features.
              </para>
            </listitem>
            <listitem>
              <para>Write bugs.  Good bugs, especially with test cases, 
              	are always appreciated.  We especially like proposals for
              	new <literal>XLint</literal> messages, since they are
              	sometimes easy to implement and help users learn
              	AspectJ, and for other implementable features
              	grounded in a compelling use-case.  
              </para>
            </listitem>
            <listitem>
              <para>Write test cases for compiler bugs without test cases.
              Compiler bugs without test cases are much less likely to be fixed;
              until they are rendered in code, they might be user mistakes,
              and they might duplicate another bug or actually cover many bugs.
              </para>
              <para>Find them by searching open compiler bugs and picking out
              any which do not have test case attachments or a comment that
              a test case has been written.  
              Here is a query for open compiler bugs:
              <!-- ulink gacks on ampersands in url value, so quote them -->
              <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&amp;component=Compiler&amp;bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED">
              http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&amp;component=Compiler&amp;bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED
              </ulink>
              </para>
              <para>For how to write test cases, see
                 <xref linkend="q:harnesstestcases"/>.
              </para>
            </listitem>
            <listitem>
              <para>Write patches to fix bugs.
              If you particularly need a bug to be fixed, or if you're interested in 
              learning about the system, then get the source code and try to fix the
              bug.  Most likely you'll want to email aspectj-dev@eclipse.org to 
              declare your intentions and the approach you propose (based on having
              looked at the code).
              Mailing the list gives those experienced with the code a chance to
              guide you away from pitfalls.  To submit the patch, attach it to
              the bug.  (When creating patches, do so on a per-module basis; that 
              means if fixing the bug involves changes to three modules, submit
              three patches.)
              </para>
            </listitem>
            <listitem>
              <para>Write patches for other reasons.
              Often documentation needs to be fixed, or there may be a small new 
              feature you'd like to see.  You can just do it and then submit it
              as a patch to a bug you create.  As with bugs, in some cases you
              might want to declare your intentions on the mailing list to avoid
              wasting time on something that's been fixed but not committed or
              on an approach that will be fruitless.
              </para>
            </listitem>
          </itemizedlist>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:buildingsource"
            xreflabel="Q:How do I get and compile the source code for AspectJ?">
          <para>How do I get and compile the source code for AspectJ?
          </para>
        </question>
        <answer>
          <para>AspectJ 1.0 source code is available in an archive available 
           with the 1.0 downloads.  It contains instructions for building
           from sources.
          </para>
			<para>AspectJ 1.1+ source code is available through CVS using the 
				CVS Root <literal>dev.eclipse.org:/cvsroot/technology</literal>. 
				For more information on accessing the CVS tree at eclipse.org, 
				see the documentation from <ulink 
				url="http://eclipse.org">http://eclipse.org</ulink>. Find 
				specific instructions in the AspectJ tree at <ulink 
				url="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.aspectj/modules/build/readme-build-and-test-aspectj.html?rev=HEAD&amp;content-type=text/html&amp;cvsroot=Technology_Project"> 
				org.aspectj/modules/build/readme-build-and-test-aspectj.html</ulink>. 
				If you would like to use Ant to checkout the sources, build the 
				distribution, and test everything, see <ulink 
				url="http://dev.eclipse.org/viewcvs/index.cgi/~checkout~/org.aspectj/modules/build/release/build.xml?rev=HEAD&amp;content-type=text/xml&amp;cvsroot=Technology_Project"> 
				org.aspectj/modules/build/release/build.xml</ulink>. </para>
          <para>
          To check out the source code in Eclipse go to (<literal>File > new > Other > CVS > Checkout Projects from CVS</literal>). You'll need about 125 MB of space for the source and build.
          	Host: <literal>dev.eclipse.org</literal>,
          	Repository Path: <literal>/cvsroot/technology</literal>,
          	user name: <literal>anonymous</literal>,
          	password: (your email address),
          	connection type: <literal>pserver</literal>,
          	default port.
			Then select the individual modules you want to check out (you probably want all of them bar aspectj-attic and java5) and click Next and choose to check out the modules you selected as Java projects.
			Once thats done each module you checked out should show up as a project in the package explorer.
			If you have problems after this point you can view the build instructions that come with AspectJ by going in the package explorer to: <literal>build > readme-build-and-test-aspectj.html</literal>.
          </para>
          <para>
            To get the modules to build you have to set some classpath variables (<literal>Window > Preferences > Java > Build Path > Classpath Variables</literal>):
          </para>
		  <para>
		  <itemizedlist>
		  	<listitem>
		  	<para>
			Name: <literal>JAVA_HOME</literal>, Value: (wherever your Java JDK is installed)
			</para>
			</listitem>
			<listitem>
			<para>
			Name: <literal>JRE14_LIB</literal>, Value: (wherever your Java 4 Runtime is installed)<literal>\jre\lib\rt.jar</literal>
			</para>
			</listitem>
			<listitem>
			<para>
			Name: <literal>JRE15_LIB</literal>, Value: (wherever your Java 5 Runtime is installed)<literal>\jre\lib\rt.jar</literal>
			</para>
			</listitem>
			<listitem>
			<para>
			Name: <literal>ASPECTJRT_LIB</literal>, Value: (wherever your workspace is)<literal>\lib\aspectj\lib\aspectjrt.jar</literal>. To find out where your workspace is go to <literal>File > Switch Workspace</literal>.
			</para>
			</listitem>
		  </itemizedlist>
		  </para>
		  <para>
		  The <literal>org.aspectj.lib</literal> project is an AspectJ project so 
          you also have to have AJDT installed. For the latest AJDT release and
          download instructions visit the
		  <ulink url="http://www.eclipse.org/ajdt/downloads/">AJDT Downloads</ulink> page.
		  </para>
			<para>
			When you've added the variables click OK to do a full rebuild, then run the tests by going in the Package Explorer to:
			<literal>run-all-junit-tests > testsrc > (default package) > RunTheseBeforeYouCommitTests.java</literal>
			and running this as a JUnit test (right click and select <literal>Run As > JUnit Test</literal>).
			Don't worry about any errors that appear in the console output,
			just check that there are no failures in the JUnit view (<literal>Window > Show View > Other > Java > JUnit</literal>).
			If that finishes with no Failures and a full green bar you have the AspectJ compiler source and it's building and testing properly.
			</para>
          <para>
          Further details:
			</para>
			<para>                             
          You can check out the entire modules directory and build using the
          Ant build script <literal>modules/build/build.xml</literal>.
          All required libraries are included in <literal>modules/lib/</literal>,
          (including Ant 1.5.1 in <literal>modules/lib/ant</literal>).
          If you are using Eclipse, you can check out any <literal>modules/</literal> 
          subdirectory as an eclipse Java project.  
          Depending on what you are trying to build, you need not check out
          all modules; as of this writing, here are the modules to get 
          for building the specific parts of AspectJ:
          </para>
          <para>
          <itemizedlist>
            <listitem><para>For any builds: build, lib
            </para></listitem>
            <listitem><para>For the documentation: docs
            </para></listitem>
            <listitem><para>For the compiler: bridge, util, testing-util,
            weaver, asm, org.eclipse.jdt.core, org.aspectj.ajdt.core,
            and runtime.
            </para></listitem>
            <listitem><para>For ajbrowser: the compiler modules, plus
            ajbrowser, ajdoc, taskdefs, and ajde.
            </para></listitem>
            <listitem><para>For the AspectJ distribution, the ajbrowser modules, 
				plus aspectj5rt and org.aspectj.lib.
            </para></listitem>
            <listitem><para>For the test harness (or to run the release build
				scripts and tests): the ajbrowser modules, plus
            testing, testing-client, and testing-drivers.
            </para></listitem>
            <listitem><para>To run the test suite: the test harness modules, plus
            tests.
            </para></listitem>
          </itemizedlist>
          </para>
          <para>
          Note that module interdependencies are recorded only in the eclipse 
          <literal>modules/{module}/.classpath
          </literal>
           files and may
          change, so the list above may not be correct when you read it.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>

        <question id="q:buildingAspectJAndAJDT"
            xreflabel="Q:How do I build AspectJ and integrate it into AJDT?">
          <para>How do I build AspectJ and integrate it into AJDT?
          </para>
        </question>
        <answer>
          <para>To build AspectJ, first get the source tree as
          described in <xref linkend="q:buildingsource"/>. Once you have
          a development environment set up, copy the 
          <literal>build/sample-local.properties</literal> file
          to <literal>build/local.properties</literal> and within this file point the 
          <literal>java14.home</literal> and <literal>java15.home</literal>
          to the corresponding places on your machine.
          </para>
			<para>
             To build AspectJ on the command line:
          </para>
		  <para>
		  <itemizedlist>
		  	<listitem>
		  	<para>
			Open a command prompt
			</para>
			</listitem>
			<listitem>
			<para>
			Navigate to the <literal>build</literal> directory within your AspectJ workspace 
			(to find out where your workspace is go to <literal>File > 
			Switch Workspace</literal> within Eclipse).
			</para>
			</listitem>
			<listitem>
			<para>
			Run <literal>ant clean</literal> to remove the files from 
			previously built AspectJ versions. 
			</para>
			</listitem>
		  	<listitem>
		  	<para>
			Run <literal>ant</literal> to build AspectJ. The built files are created in 
			<literal>your_eclipse_installation_directory/aspectj_development_workspace/aj-build</literal>.
			</para>
			</listitem>
		  </itemizedlist>
		  </para>
			<para>
			To import a locally built AspectJ into AJDT first follow the
			instructions on <ulink url="http://www.eclipse.org/ajdt/faq.php#q:develop">
			How do I setup an AJDT development environment in Eclipse?</ulink>
			for setting up an AJDT development environment and running the 
			correctness tests. Then:
			</para>
		  <para>
		  <itemizedlist>
		  	<listitem>
		  	<para>
			Create a file <literal>aspectjlib.properties</literal> within 
			the <literal>org.aspectj.ajde</literal> project and add the following two lines
			<programlisting>
aspectj.lib.dir=C:/eclipse/aspectj-workspace/aj-build/dist/tools/lib
aspectj.doc.dir=C:/eclipse/aspectj-workspace/aj-build/dist/ide/eclipse/org.aspectj.ajde.doc/doc
			</programlisting>
  			making sure to change the path to correspond to your set up.
			</para>
			</listitem>
			<listitem>
			<para>
			Run the <literal>build.xml</literal> file in <literal>org.aspectj.ajde</literal> 
			with the <literal>plugin jars</literal> target:
			<itemizedlist>
		  	   	<listitem>
		  		<para>
	 			Right click on the <literal>build.xml</literal> file in the 
	 			<literal>org.aspectj.ajde</literal> plugin
	 			</para>
	 			</listitem>
				<listitem>
	 			<para>
				Select <literal>Run As > Ant build...</literal>
				</para>
				</listitem>
				<listitem>
				<para>
				In the resultant dialog navigate to the <literal>Targets</literal> tab
				</para>
				</listitem>
				<listitem>
				<para>
				Ensure <literal>plugin jars</literal> is the only selected target
				</para>
				</listitem>
				<listitem>
				<para>
				Click <literal>Run</literal>
				</para>
				</listitem>
			</itemizedlist>	
			</para>
			</listitem>
			<listitem>
			<para>
			Refresh the <literal>org.aspectj.ajde, org.aspectj.runtime</literal> 
			and <literal>org.aspectj.weaver</literal> plugins.
			</para>
			</listitem>
		  </itemizedlist>
		  </para>					
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:devDocs"
            xreflabel="Q:Where do I find developer documentation on building and testing AspectJ source code?">
          <para>Where do I find developer documentation on building and testing AspectJ source code?
          </para>
        </question>
        <answer>
          <para>Find the developer documentation in HTML files in the CVS tree,
          inside the <literal>build</literal> and <literal>testing</literal> modules 
          (i.e., in <literal>org.aspectj/modules/build/...</literal>).
          Most pertinant:          
            <itemizedlist>
              <listitem><para>
              	<literal>../build/readme-build-and-test-aspectj.html</literal>
                  describes how to build the AspectJ distribution in Eclipse
                  and in Ant.
              </para></listitem>
              <listitem>
              	<para><literal>../build/readme-docs-module.html</literal>
                  describes the AspectJ documentation sources and
                  how to build the documentation using Ant.
              </para></listitem>
              <listitem><para><literal>../build/readme-tests-module.html</literal>
                  describes the all the tests 
                  in the <literal>tests</literal> module.
              </para></listitem>
              <listitem><para><literal>../build/readme-writing-compiler-tests.html</literal>
                  describes how to write compiler tests that can be run by
                  the AspectJ test harness.
              </para></listitem>
              <listitem><para><literal>../build/readme-testing-drivers-module.html</literal>
                  describes the test harness used to run the compiler tests
                  in the <literal>tests</literal> module.
              </para></listitem>
              <listitem><para><literal>../build/readme-testing-drivers-module.html</literal>
                  describes the test harness used to run the compiler tests
                  in the <literal>testing</literal> module.
              </para></listitem>
            </itemizedlist>
          </para> 
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:harnesstestcases"
            xreflabel="Q:How should I submit test cases for bugs?">
          <para>How should I submit test cases for bugs?
          </para>
        </question>
        <answer>
          <para>You can attach files to a bug after it has been created.
          The code of course should replicate the actual behavior
          described in the bug when run on the target version.
          If you have a single source file, you can attach it directly,
          describing in the comments the expected result
          (e.g., error on line 14, or successful compile/run).
          The most helpful form for describing the test scenario
          and the expected results are the test definitions
          described next.
          </para>
          <para>For more complex bugs requiring many files, 
          create a zip file of a directory containing all the files
          and an XML test definition file.  
          The XML test definition file contains specifications
          for how to compile, recompile, or run the test sources.
          Complete documentation is available in the CVS tree
          at <literal>tests/readme-writing-compiler-tests.html</literal>
          but here is a sample file with some example definitions,
          preceded by comments showing the directory layout
          of the files referred to in the test definitions.
          </para>
          <para>
          <programlisting>
<![CDATA[
<!DOCTYPE suite SYSTEM "../tests/ajcTestSuite.dtd">
<suite>

<!-- Compile and run
     using the following files:

       {testDefinitions}.xml
       one/
         pack1/
           Main.java
         p2/
           BeforeConstructor.java

    Note the bug number goes in the pr attribute.
    ("pr" stands for "problem report")
 -->
<ajc-test dir="one" pr="234" title="before constructor call">
    <compile files="pack1/Main.java,p2/BeforeConstructor.java"/>
    <run class="pack1.Main"/>
</ajc-test>

<!-- Check that compiler warning was emitted 
     using the following files:

       {testDefinitions}.xml
       two/
         UsesDeprecated.java
 -->
<ajc-test dir="two" pr="244" title="deprecated, noImportError">
    <compile options="-warn:deprecated,-noImportError" 
          files="UsesDeprecated.java">
        <message kind="warning" line="20"/>
    </compile>
</ajc-test>

<!-- Cooked example that uses all compiler attributes 
     and the following files:
       {testDefinitions}.xml
       testCaseDir/
         jars/
           injar.jar
           required.jar
           requiredAspects.jar
         pack/
           Main.java
         providedClassesDir/
           ClassInDefaultPackage.class
           org/
             foo/
               AnotherRequired.class
  -->
<ajc-test dir="testCaseDir" title="attributes test">
    <compile files="pack/Main.java,jars/injar.jar" 
           staging="true"
           options="-Xlint,-g:none"
          argfiles="debug.lst,aspects/test.lst"
        aspectpath="jars/requiredAspects.jar"
         classpath="providedClassesDir,jars/required.jar"/>
    <run class="Main"/>
</ajc-test>

<!-- Compiler errors, recompile after changing files, and run
     using the following files:

       {testDefinitions}.xml
       three/
         pack/
           IncCompileFix.java
           IncCompileFix.20.java

     Before compiling, IncCompileFix.java is copied to a staging
     directory.  Before recompiling, IncCompileFix.20.java 
     replaces it, so the compiler treats file as updated.
  -->
<ajc-test dir="three" pr="622" title="incremental fix">
    <compile staging="true" files="pack/IncCompileFix.java">
        <message kind="error" line="20"/>
        <message kind="error" line="42"/>
    </compile>
    <inc-compile tag="20"/>
    <run class="pack.IncCompileFix"/>
</ajc-test>

</suite>
]]>
          </programlisting>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:testharness"
            xreflabel="Q:I'd like to run my test case.  How do I get the test harness?">
          <para>I'd like to run my test case.  How do I get the test harness?
          </para>
        </question>
        <answer>
          <para>The test harness is not distributed.
          To build it, get the source tree as
          described in <xref linkend="q:buildingsource"/> and then
          build the <literal>build-testing-drivers</literal> target:
          <programlisting>
  cd build
  ../lib/ant/bin/ant -f build.xml build-testing-drivers
          </programlisting>
          This produces 
          <literal>../aj-build/jars/testing-drivers-all.jar</literal>
          which you can run as described in
          <literal>tests/readme-tests-module.html</literal>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:bcel"
            xreflabel="Q:BCEL is used by AspectJ but it's not actively developed.  Will you change?">
          <para>BCEL is used by AspectJ but it's not actively developed.  Will you change?
          </para>
        </question>
        <answer>
          <para>The AspectJ bytecode weaver has used BCEL for bytecode manipulation
			  since its first release.  We have upgraded it extensively, to improve 
			  performance, support Java 5, etc.  The BCEL developers have not
			  incorporated our patches, so we continue to maintain our own version.
			  Ours has been optimized for the AspectJ weaver and battle-hardened 
			  over years of development and use.  At some point in the future,
			  the AspectJ weaver might be restructured to make it easy to see 
			  whether another bytecode package offers the same stability, 
			  functionality, and performance, but for now we prefer using something
			  that we know works well.
          </para>
          <para>
			  In the AspectJ 5 release, the weaver has been restructured to
			  use reflection where possible.  Otherwise, it
			  continues to use BCEL, but does not hold BCEL structures in
			  memory after our evaluation completes.
          </para>
        </answer>
      </qandaentry>
	</qandadiv>

    <qandadiv id="help" xreflabel="Getting Help">
      <title>Getting Help</title>
      <qandaentry>
        <question id="q:moreaboutaj"
            xreflabel="Q:How do I find out more about AspectJ?">
          <para>
            How do I find out more about AspectJ?
          </para>
        </question>
        <answer>
          <para>Visit the AspectJ project web site:
            <ulink url="http://eclipse.org/aspectj">http://eclipse.org/aspectj</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:bugreports"
            xreflabel="Q:How do I submit a bug report?">
          <para>How do I submit a bug report?</para>
        </question>
        <answer>
          <para>You can submit a bug from 
              <ulink url="http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ">
                          http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ
              </ulink>.
            If it seems to be a bug in the compiler,
            please attach a small test case (source code) 
            to reproduce the problem.
            For more information on writing compiler test cases, see
            <xref linkend="q:ajcbugs"/>.
            If you are unable to submit a test case, consider submitting traces,
            ajcore files, and/or .class dump files, as described in the
            <ulink url="pdguide/index.html">AspectJ Problem Diagnosis Guide</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:talktousers"
            xreflabel="Q:How do I communicate with other AspectJ users?">
          <para>
            How do I communicate with other AspectJ users?
          </para>
        </question>
        <answer>
          <para>You can reach other AspectJ users by using the
            aspectj-users mailing list.  You can subscribe to the list or view the
            list archives from the AspectJ home page
            <ulink url="http://eclipse.org/aspectj">
              http://eclipse.org/aspectj
            </ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:searchingsite"
            xreflabel="Q:How can I search the email archives or the web site?">
          <para>
            How can I search the email archives or the web site?
          </para>
        </question>
        <answer>
          <para>
			It is very effective to do a google search of the form,
            <ulink url="http://www.google.com/search?q=site:eclipse.org+cflowbelow">
              http://www.google.com/search?q=site:eclipse.org+cflowbelow
            </ulink>,
    		and you can use the eclipse.org search at
            <ulink url="http://www.eclipse.org/search/search.cgi">
              http://www.eclipse.org/search/search.cgi
            </ulink>.
		    You can also check the old archives available for download from
    		the AspectJ home page
    		<ulink url="http://eclipse.org/aspectj">
              http://eclipse.org/aspectj
            </ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:writingbugsandemails"
            xreflabel="Q:How should I write email queries?">
          <para>
            How should I write email queries?
          </para>
        </question>
        <answer>
              <para>Here's the general form of a good email:
              </para>
          <orderedlist>
            <listitem>
              <para>
                Describe the big picture of what you are trying to do...
              </para>
            </listitem>
            <listitem>
              <para>
  	Describe what you think it takes, in AspectJ terms
  	(concepts, syntax, and semantics) from the 
            <ulink url="progguide/index.html">Programming Guide</ulink>...
              </para>
            </listitem>
            <listitem>
              <para>
	Show the AspectJ code you are using, what output it
  	produces when run, and what output you expect...
              </para>
            </listitem>
          </orderedlist>
          <para>
	The big picture helps others redirect you to other approaches.
	Using AspectJ terms helps others correct mistakes in thinking
	about the problem (the most common being to confuse join points
	and pointcuts).
           The code is key to clarifying your question and getting a good
           response.  On the mail list, someone can reply by fixing your 
           code.  In bugs, the developers can reproduce the problem immediately
           and start analyzing the fix.
           The code should not be incomplete; it should run (or fail) as-is,
           without additional libraries or source files.
          </para>
          <para>
             For the mail lists, we try to follow the conventions for open-source
             discussions that help avoid "the tragedy of the commons." 
             For example conventions, see
            <ulink url="http://jakarta.apache.org/site/mail.html">
              http://jakarta.apache.org/site/mail.html
            </ulink> and
            <ulink url="http://www.tuxedo.org/%7Eesr/faqs/smart-questions.html">
              http://www.tuxedo.org/%7Eesr/faqs/smart-questions.html
            </ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:idebugs"
            xreflabel="Q:How do I write bugs for the IDE support?">
          <para>
            How do I write bugs for IDE support?
          </para>
        </question>
        <answer>
          <para>
          Bugs appearing in the IDE's may apply to the affected IDE
          or to the compiler.  Compiler stack traces in IDE message windows
          are prefixed "Internal Compiler Error" and should be written up
          as compiler bugs.  If you are unsure, try redoing the compile
          from the command line.
          </para>
          <para>
          Bug report for the IDE extensions go to their respective projects,
          listed in
             <xref linkend="q:integrateWithDevTools"/>
          (including bug reports for the AJDE Eclipse support,
          which you can submit at
            <ulink url="http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AJDT">
                        http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AJDT
            </ulink>).
          </para>
          <para>
        Bug reports on ajbrowser should have version
	information for both Java and AspectJ, and
	(most importantly) clear steps for reproducing the bug.  
        You may submit ajbrowser bugs against the IDE component of AspectJ 
        via the web form 
            <ulink url="http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ">
                        http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ
            </ulink>.
          </para>
          <para>
	One of the benefits of open-source is that you can
	find and fix the bug for yourself; when you submit
	the fix back to us, we can validate the fix for you
	and incorporate it into the next release.  
    You can submit a patch by attaching it to the bug.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:ajcbugs"
            xreflabel="Q:How do I write bugs for the AspectJ compiler?">
          <para>
            How do I write bugs for the AspectJ compiler?
          </para>
        </question>
        <answer>
          <para>
	The best compiler bug report is a reproducible test case, 
	standalone code that demonstrates the problem.
	Sometimes with aspects, a test case requires several 
	files, if not some way to capture the behavior.
	Here's how we recommend submitting test cases:
            <orderedlist>
              <listitem>
                <para>
	Write the test case so that when the compiler bug 
  	is fixed, the test completes normally without output
  	(e.g., expected compiler errors are issued,
   	or classes produced run correctly).  This usually
    means writing one or more source files.
                </para>
              </listitem>
              <listitem>
                <para>
	In the bug report, briefly summarize the bug.
	If it is not obvious, be sure to specify 
	the expected output/behavior (e.g., compiler error on line 32)
	and, if the compile should complete, the main class to run.
                </para>
              </listitem>
              <listitem>
                <para>
	Submit the bugs via the web form 
            <ulink url="http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ">
                        http://bugs.eclipse.org/bugs/enter_bug.cgi?product=AspectJ
            </ulink>.
                </para>
              </listitem>
              <listitem>
                <para>Attach the test case to the bug.
                The test case may be a single file
                or it may be multiple files in a single zip archive,
                of the form discussed in
                <xref linkend="q:harnesstestcases"/>.
                </para>
              </listitem>
            </orderedlist>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:teachingmaterials"
            xreflabel="Q:Can you recommend reading or teaching material for AspectJ?">
          <para>
            Can you recommend reading or teaching material for AspectJ?
          </para>
        </question>
        <answer>
          <para>The documentation available in the distribution is the 
          best source for language and usage questions.  You can also find
          selected AspectJ papers and presentations on the 
          <ulink url="http://www.parc.com/groups/csl/projects/aspectj/index.html">
                            PARC AspectJ page</ulink>.
          For links to Aspect-oriented programming materials in general, see
          <ulink url="http://aosd.net">http://aosd.net</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:consulting"
            xreflabel="Q:Where can our group get consulting and support?">
          <para>
            Where can our group get consulting and support?
          </para>
        </question>
        <answer>
          <para>The best thing to to is join and email the
           <literal>aspectj-dev@eclipse.org</literal> mailing list.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:faqchanges"
            xreflabel="Q:What has changed since the last FAQ version?">
          <para>
            What has changed since the last FAQ version?
          </para>
        </question>
        <answer>
          <para>
          Entries changed recently:
            <itemizedlist>
        <listitem><para><xref linkend="q:license"/></para></listitem>
        <listitem><para><xref linkend="q:productplans"/></para></listitem>
        <listitem><para><xref linkend="q:whitepapers"/></para></listitem>
        <listitem><para><xref linkend="q:bugreports"/></para></listitem>
            </itemizedlist>
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
    <qandadiv id="project" xreflabel="About the AspectJ Project">
      <title>About the AspectJ Project</title>
      <qandaentry>
        <question id="q:opensource"
            xreflabel="Q:What does the fact that AspectJ is an Open Source Project mean to me?">
          <para>What does the fact that AspectJ is an Open Source
            Project mean to me?
          </para>
        </question>
        <answer>
          <para>Open source protects your interest in a correct, long-lived,
		up-to-date, and widely-accepted implementation of AspectJ.
            <itemizedlist>
              <listitem>
                <para>With the source code, you control your own destiny
                in perpetuity.  You can continue to use the implementation
		and update it as necessary to fix bugs and add things you need.
                </para>
              </listitem>
              <listitem>
                <para>Because the code is available to all, anyone can find
		and fix bugs.  There is no need to hope for it to be fixed
		in the next product release.  Those who encounter the bugs
		are motivated to fix them, and there are more eyeballs on 
		the code than in closed-source, so the quality tends to be high.
		This can be particularly true for the AspectJ community,
		which tends to be highly skilled.
                </para>
              </listitem>
              <listitem>
                <para>The same is true of new features or behavior, so the
		implementation should be up-to-date.  This is important as
		the field of AOP develops, to capture the latest solutions.
                </para>
              </listitem>
              <listitem>
                <para>For a programming language which forms the basis of 
		an entire solution stack, open source facilitates the kind
		of adoption -- tool integrations and significant projects --
		that develop and prove the technology for wider adoption.  This 
		limits delays caused by waiting for the completion of standards 
		process or promulgation by industry leaders, and also provides
	        the proofs necessary for such adoption.
                </para>
              </listitem>
            </itemizedlist>
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:standardization"
            xreflabel="Q:What are your plans to make AspectJ a general feature of Java supported by Sun and the other key-players in the Java Industry?">
          <para>What are your plans to make AspectJ a general feature
            of Java supported by Sun and the other key players in the Java
            Industry?
          </para>
        </question>
        <answer>
          <para>Although we are committed to making AspectJ available to a wide
            range of users, it is too early to decide on a strategy. Some
            options include continuing AspectJ as a stand-alone product,
            integrating it into IDEs, or possibly incorporating it into
            standard Java with Sun's blessing.
          </para>
          <para>We currently focus on developing for the 1.1 implementation 
            which improves AspectJ in key areas: rapid
            incremental compilation, bytecode weaving, and IDE integration.
          </para>
          <para>Through all of this our goal is to make AspectJ integrate as
            seamlessly as possible with the Java programming language. The
            AspectJ language design is becoming more integrated, the compiler
            is becoming faster and more integrated, the IDE extensions are
            becoming more integrated. All of this is designed to help users
            really use AspectJ and give us feedback on it.
          </para>
          <para>As the system is improved and we work more closely
            with users, we will be in good position to explore the best path
            for AspectJ in the long term.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:bytecodeweaving"
            xreflabel="Q:When will AspectJ work from class files? When will it work at class-loading time?">
          <para>When will AspectJ work from class files?
	        When will it work at class-loading time?
          </para>
        </question>
        <answer>
          <para>Bytecode weaving is in AspectJ 1.1.  We believe it
	   works as described in an email to the users list by Jim Hugugin:
          </para>
          <para>
              The AspectJ language was designed to support weaving at many different times: 
              compile, load, or even run-time in the JVM.  Weaving into bytecodes at both 
              compile and load-time will definitely be provided in a future release.  This 
              will allow weaving at compile-time into libraries for which source code is 
              not available.  It will also support aspect-aware class loaders that can 
              perform weaving at load time on arbitrary classes.  One advantage of a 
              language like AspectJ, rather than an explicit meta-tool like jiapi, is 
              that it separates the specification of a crosscutting concern from any 
              particular implementation strategy for weaving.
          </para>
          <para>
              ...AspectJ provides a language that can cleanly 
              capture crosscutting concerns while preserving the static type checking, 
              modularity, and composability of Java.
          </para>
          <para>If you have an application for using aspects and bytecode, 
              please let the AspectJ team know of your requirements.
              We expect to have a demonstration classloader available in
              the 1.1 release or soon thereafter.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:differences"
            xreflabel="Q:What are the differences between the current and previously released versions of AspectJ?">
          <para>What are the differences between the current and
            previously released versions of AspectJ?
          </para>
        </question>
        <answer>
	  <para>The AspectJ team aims to keep the implementation bug-free and 
	  	up-to-date with the Java language, 
	 	to limit AspectJ language changes to those that 
		are carefully considered, compelling, and backwards-compatible,
		and to deliver those language changes only in significant releases (1.0, 1.1).
	  </para>
          <table>
            <title></title>
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry align="left">Version</entry>
                  <entry align="left">Description</entry>
                </row>
                <row>
                  <entry>AspectJ 1.5</entry>
                  <entry>Upgrade to support Java 5 language and much better
                      load-time weaving.
                  	See <ulink url="README-150.html">README-150.html</ulink>
                  	for more details.
                  </entry>
                </row>
                <row>
                  <entry>AspectJ 1.1</entry>
                  <entry>A few language changes and clarifications;
                  	bytecode weaving and incremental compilation.
                  	See <ulink url="README-11.html">README-11.html</ulink>
                  	for more detail.
                  </entry>
                </row>
                <row>
                  <entry>AspectJ 1.0</entry>
                  <entry>Many language changes, fixes, cleanup and
                    clarifications, some significant.
                  </entry>
                </row>
                <row>
                  <entry>AspectJ 0.8</entry>
                  <entry>More cleanup of the syntax and semantics.</entry>
                </row>
                <row>
                  <entry>AspectJ 0.7</entry>
                  <entry>Clean up of the semantics, 0.7 beta 4 is the first
                    open source release.
                  </entry>
                </row>
                <row>
                  <entry>AspectJ 0.6</entry>
                  <entry>Advice and crosscuts get explicit type signatures
                    which describe the values that are available to advice at a
                    crosscut.
                  </entry>
                </row>
                <row>
                  <entry>AspectJ 0.5</entry>
                  <entry>Improved tool support: better Emacs environment
                    support and <literal>ajdoc</literal> to parallel
                    <literal>javadoc</literal>. around advice is added, and the
                    <literal>aspect</literal> keyword is removed and replaced
                    by the Java keyword class.
                  </entry>
                </row>
                <row>
                  <entry>AspectJ 0.4</entry>
                  <entry>Clear separation of crosscuts and crosscut actions
                    makes it possible to define extensible library
                    aspects.
                  </entry>
                </row>
                <row>
                  <entry>AspectJ 0.3</entry>
                  <entry>First all Java implementation, also includes many
                    small language improvements.
                  </entry>
                </row>
                <row>
                  <entry>AspectJ 0.2</entry>
                  <entry>General-purpose support for crosscutting. Users could
                    program any kind of aspects, not just coordination. This
                    release dropped COOL.
                  </entry>
                </row>
                <row>
                  <entry>AspectJ 0.1</entry>
                  <entry>A single domain-specific aspect language, called COOL,
                    for programming coordination in multi-threaded
                    programs.
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
          <para> More details for 1.0 and earlier releases are available in 
            <ulink url="changes.html">changes.html</ulink>.
          </para>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:schedule"
            xreflabel="Q:What is the AspectJ development schedule?">
          <para>
            What is the AspectJ development schedule?
          </para>
        </question>
        <answer>
          <para>
            Below is a table describing the goals for the major releases.
            For information about specific features, search the bug database
            for <literal>RFE</literal>'s ("requests for enhancement") by
            <ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?product=AspectJ&amp;bug_severity=enhancement">
            	selecting severity of "enhancement"</ulink>.
     
            Like many open-source projects, we don't make or promise
            schedules, but we do follow a pattern of issuing preview releases 
            which can give observers an idea of when
            a particular release might be available.
          </para>
          <table>
            <title>The AspectJ Development Schedule</title>
            <tgroup cols="2">
              <tbody>
                <row>
                  <entry align="left">Version</entry>
                  <entry align="left">Description</entry>
                </row>
                <row>
                  <entry valign="top" align="center">1.0</entry>
                  <entry>Final syntax and semantic changes. Standalone structure
                    browser. Complete documentation.
                  </entry>
                </row>
                <row>
                  <entry valign="top" align="center">1.1</entry>
                  <entry>Faster incremental compilation, bytecode weaving,
	                 and a small number of language changes.</entry>
                </row>
                <row>
                  <entry valign="top" align="center">1.2</entry>
                  <entry>Faster weaving, -inpath option, better error messages,
                  better handling of binary input and resources
                  during incremental compilation, faster runtime
                  </entry>
                </row>
                <row>
                  <entry valign="top" align="center">1.5 (AspectJ 5)</entry>
                  <entry>Support for Java 1.5, generic aspects,
                      annotations, etc.  Integrates AspectWerkz-style
                      load-time weaving.
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </answer>
      </qandaentry>
      <qandaentry>
        <question id="q:java5"
            xreflabel="Q:Will AspectJ support Java 5?">
          <para>
            Will AspectJ support Java 5?
          </para>
        </question>
        <answer>
          <para>
          Yes.  Java 5 is supported in AspectJ 5.
          </para>
        </answer>
      </qandaentry>
    </qandadiv>
  </qandaset>
  <para>AspectJ is a registered trademark of Palo Alto Research Center, Incorporated (PARC),
  	used with permission.
	Java and all Java-based marks are trademarks or registered trademarks of
    Sun Microsystems, Inc. in the United States and other countries. All other
    trademarks are the property of their respective owners.
  </para>
</article>
<!--
Local variables:
compile-command: "java com.icl.saxon.StyleSheet -o faq.html faq.xml /usr/local/docbook/docbook-xsl-1.44/html/docbook.xsl"
fill-column: 79
sgml-local-ecat-files: faq.ced
End:
-->