<refentry>
  <refnamediv>
    <refname>AspectJ Browser</refname>

    <refpurpose>GUI tool for compiling programs with ajc and navigating the
    crosscutting structure</refpurpose>

  </refnamediv>

    <refsect1 id="ajbrowser" xreflabel="AspectJ Browser">
        <title>Overview</title>


        <para>
            The AspectJ Browser can edit program source files,
            compile using the AspectJ compiler
            <xref linkend="ajc">ajc</xref>, 
            run a program,
            and graphically navigate the program's 
            crosscutting structure.
        </para>
        <para>
            Launch the browser from the command line either
            by typing "ajbrowser" to invoke the script in
            <literal>{aspectj}/bin</literal>
             (if AspectJ is installed correctly) 
            or by using the
            <literal>aspectjtools.jar</literal> directly:
            <programlisting>
  java -jar aspectj1.1/lib/aspectjtools.jar ...                    
            </programlisting>
        </para>

    </refsect1>

    <refsect1>
        <title>Program Build Configurations</title>

        <para>
        	To work with a particular program, point the 
        	AspectJ browser to the program source files
        	listed in a ".lst" build configuration file.
            (Build configuration files are described 
			in the documentation for 
			<xref linkend="ajc">ajc</xref>.)
            Open a build configuration file from the GUI using
            the File menu, "open" item, or by using the 
            "Open Build Configuration" button
	        (<inlinemediaobject>
	           <imageobject>
	             <imagedata fileref="openConfig.gif"/>
	           </imageobject>
	        </inlinemediaobject>).
            From the command line
            you can also pass any number of ".lst" paths. 
            (If you pass in any non-".lst" arguments, it will run the
            command-line compiler directly.)
        </para>
        <para>
            You can work with multiple build configurations;
            select, add, or remove them
            using the corresponding toolbar buttons.  
        </para>
        <para>Global build options are stored in an 
        <literal>.ajbrowser</literal> file in your HOME directory.
        Edit these from the GUI by clicking the "Options" button 
        or selecting the Tools menu item "Options...".  
        This is how you can set classpath, aspectpath, etc.
        (ajbrowser, unlike ajc, does not support setting these 
        options from the ".lst" files.).
        </para>
    </refsect1>
  <refsect1>
    <title>Compiling a Program Build Configuration</title>

    <para>
        To compile click the "Build" button
        (<inlinemediaobject>
           <imageobject>
             <imagedata fileref="build.gif"/>
           </imageobject>
        </inlinemediaobject>), or click &lt;ctrl&gt;F11.  
        You may select
        from different build configurations in the GUI
        (see label 1 in the graphic below).
        (If you get classpath or other errors, set up the
        global build options as described above.)
    </para>
          <imageobject>
            <imagedata fileref="ajbrowser-building.gif"/>
          </imageobject>
  </refsect1>

  <refsect1>
    <title>Navigating the Program Structure</title>

    <para>
        Select nodes in the program structure by clicking them (see label 2).
        If one node is related to one or more other nodes by an association the
        name of the association will appear below that node and will be
        displayed in italics.  Links to other structure nodes appear in blue
        below the association.  If there is no corresponding source for the
        link it will appear light-blue.
    </para>

  </refsect1>

    <refsect1>
        <title>Example: Exploring the "Spacewar" sample code </title>
        <para>
        <itemizedlist>

          <listitem> <para>Launch <literal>ajbrowser</literal></para>
            </listitem>

          <listitem> Choose "File -&gt; Open" or click the "Open Build
          Configuration" button
           (<inlinemediaobject>
             <imageobject>
               <imagedata fileref="openConfig.gif"/>
             </imageobject>
          </inlinemediaobject>) and select the configuration file for debugging
          the spacewar example, in
          <literal>examples/spacewar/debug.lst</literal>.
            </listitem>

          <listitem> <para>Click the "Build" button (<inlinemediaobject>
           <imageobject>
             <imagedata fileref="build.gif"/>
           </imageobject>
        </inlinemediaobject>) to
             compile.  The left pane should fill with a spacewar declaration
             tree.  If there is a compiler error, the clickable error message
             shows up as in label 4.
              </para>

              <para>Note: If you did not install in the default location, the
          compile will fail with a message that you need to install
          aspectjrt.jar on your compile classpath.  To do that, select "Tools
          -&gt; Options" or click the "Options" button
          (<inlinemediaobject>
           <imageobject>
             <imagedata fileref="browseroptions.gif"/>
           </imageobject>
        </inlinemediaobject>).  Click the <literal>Build Options</literal> tab
           to view the Build Paths pane.  Edit the classpath entry to use your
           install location, ok the dialog, and retry the compile.

              </para>

              <para>
          <imageobject>
            <imagedata fileref="ajbrowser-options.gif"/>
          </imageobject>
              </para>

            </listitem>

          <listitem> <para>Different structure views: The structure tree at the
          left can display different orderings and granularity for structure:

           <itemizedlist>
            <listitem> The package hierarchy view shows the traditional hierarchy
               of package, class, and members. </listitem>

            <listitem> The inheritance view shows the hierarchy from topmost
               parent classes through subclasses to members. </listitem>

            <listitem> The crosscutting view shows the aspect members
               and the code they affect. </listitem>

            <listitem> Additional buttons in the pane can be used to change the
               granularity and filter out items.
            </listitem>

           </itemizedlist>

             </para>

             <para>Whenever you select an item in the tree view, the
                   source pane scrolls to that item. If you select a leaf item
                   representing another program element, then the tree
                   selection will go to the corresponding node.  (See below for
                   how to use two panes to maintain your place.)
             </para>

          </listitem>
          <listitem>

             <para>When working with aspects, it helps to be able to navigate
               between different program elements:
             </para>

            <itemizedlist>

              <listitem><para>When looking at a method, find the advice that
              affects it.  </para></listitem>

              <listitem><para>When looking at a pointcut, find the advice that
              uses it.  </para></listitem>

              <listitem><para>When looking at advice, find what it advises -
              e.g., method calls or executions, initializers, etc.
              </para></listitem>

              <listitem><para>When looking at a type, find any aspects that
                              declare members or supertypes of the type, or
                              vice-versa.
              </para></listitem>

            </itemizedlist>

             <para>You can view the advice on a particular method using the
                   default, hierarchical view.  Navigate to the tree item for
                   <literal>spacewar.Registry.register(SpaceObject)</literal>
                   in the <literal>debug.lst</literal> config file.  Now, in
                   the lower, file view, you can see and navigate to the advice
                   using the subtree whose parent is the <literal>method
                   affected by</literal> relation.
             </para>

             <para>You can also use crosscutting view to see the
                   advice using a pointcut or the methods affected by advice.
                   For example, to see what advice uses a particular pointcut,
                   navigate to the tree item for the pointcut
                   <literal>spacewar.Debug.allConstructorsCut()</literal> in
                   the <literal>debug.lst</literal> config file.  You can see
                   and navigate to the advice that uses the pointcut using the
                   <literal>pointcut used by</literal> relation.
             </para>

             <para>As an example of seeing the methods affected by advice,
                   while still in the same view, select the first
                   <literal>before</literal> advice in
                   <literal>spacewar.Debug</literal>.  It has relation
                   sub-trees for both <literal>uses pointcut</literal> and
                   <literal>affects constructions</literal>.  The
                   <literal>affects</literal> relations will list different
                   kinds of join points - constructor or method calls, etc.
             </para>
             <para>Note that the AspectJ browser can only display 
             static structure (whether hierarchical or crosscutting).
             That means that dynamicly-determined pointcuts (like
             <literal>cflow(pointcut)</literal>) 
             will not be shown as picking out static points in
             source code.  Displayable pointcuts roughly correspond
             to those that can be used in a 
             <literal>declare error</literal> statement.
             </para>
          </listitem>
        </itemizedlist>
      </para>
    </refsect1>
</refentry>

<!-- Local variables: -->
<!-- fill-column: 79 -->
<!-- sgml-local-ecat-files: devguide.ced -->
<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") -->
<!-- End: -->