path: root/docs/devGuideDB/ajbrowser.xml

<chapter id="ajbrowser" xreflabel="AspectJ Browser">

  <title>AspectJ Browser</title>

  <sect1 id="ajbrowser-intro">
	<title>Introduction</title>
	<para>
	AJBrowser presents a GUI for compiling programs with ajc
	and navigating crosscutting structure.
	</para>
        <para>
            The AspectJ Browser can edit program source files,
            compile using the AspectJ compiler <literal>ajc</literal>
            run a program,
            and graphically navigate the program's
            crosscutting structure.
            For more information on <literal>ajc</literal>,
            see <xref linkend="ajc-ref"/>.


        </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,
            and specifying no arguments or some number of
            build configuration files
            (suffix <literal>.lst</literal>):
            <programlisting>
java -jar aspectj1.1/lib/aspectjtools.jar aspectj1.1/doc/examples/spacewar/debug.lst
            </programlisting>
        </para>

    </sect1>

    <sect1 id="ajbrowser-building">
        <title>Building Programs</title>
	    <sect2 id="build-configurations" xreflabel="build-configurations">
        <title>Build Configurations</title>

        <para>A build configuration is a set of files to compile for a
        program (and optionally some additional compile arguments).
        Because <literal>ajc</literal> requires all sources to be specified
        (at least using the <literal>-sourceroots</literal> option),
        most users create <literal>.lst</literal> files that list
        the files to compile (one argument per line, globbing
        permitted - for more details, see <xref linkend="ajc-ref"/>).
        </para>
        <para>
        	To work with a particular program, select the
        	corresponding ".lst" 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>).

            You can populate the build list from the command line
            by passing any number of ".lst" paths.
            (However, if you pass in any non-".lst" arguments,
            it will run the command-line compiler directly.)
        </para>
        <para>
            To switch between 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 to set classpath, aspectpath, etc.
        </para>
        <para>The following sections walk through a build.
        </para>
	    </sect2>
	    <sect2 id="compiling-a-program-build-configuration" xreflabel="compiling-a-program-build-configuration">
    	<title>Compiling a Program Build Configuration</title>

    <para>
        To compile click the "Build" button
        (<inlinemediaobject>
           <imageobject>
             <imagedata fileref="build.gif"/>
           </imageobject>
        </inlinemediaobject>), or
		or use the tools menu.
	</para>
<!--
    <para>To build using AspectJ 1.1's incremental mode,
    click the <literal>incremental compile</literal> checkbox in
    the <literal>AspectJ Build Options</literal> tab
    of the <literal>Options</literal> dialog.
    Once in incremental mode, you can force a full rebuild
    by holding the shift key down when selecting the
    build menu item or button.
    </para>
-->
	<para>
        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>
    <para>
      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="ajbrowser-building.gif"/>
        </imageobject>
      </inlinemediaobject>
    </para>
  </sect2>
  </sect1>

  <sect1 id="ajbrowser-navigating">
    <title>Navigating 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>
    <para>
      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="ajbrowser-building.gif"/>
        </imageobject>
      </inlinemediaobject>
    </para>

  	<sect2 id="example" xreflabel="example">
        <title>Example: Exploring the "Spacewar" sample code </title>
        <para>
        <itemizedlist>

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

          <listitem> <para>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>.</para>
            </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 set up your classpath, 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.  For example, if you ran from the base Aspectj
           directory, the classpath need only include
           <literal>lib/aspectjrt.jar</literal> (though the browser may populate
           the classpath with the bootclasspath and classpath initially.)
           Be sure to use the
           <literal>lib/aspectjrt.jar</literal> that came with the browser.
              </para>

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

          </listitem>

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

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

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

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

            <listitem><para>Additional buttons in the pane can be used to change the
               granularity and filter out items.</para>
            </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>
    </sect2>
    </sect1>
  <sect1 id="ajbrowser-running">
    <title>Running Programs</title>
    <para>
    The browser supports a limited form of running compiled programs.
    To run programs that have been built, click the run button
    or select one of the run menu items in the project menu.
    You can run in the same VM or spawn a new process;
    the latter is generally better for GUI programs.
    </para>
    <para>Both require that any classpath you set be specified
    using platform-specific paths and path separators (the
    compiler might be more tolerant).
    Output and error streams will be
    merged into the streams of the browser (using separate
    threads, so it may take a few seconds for the pipe
    threads to gain control.) Errors should
    be detected and displayed in a dialog.
    </para>
    <para>
    The GUI does not support killing a running program,
    so if your program might hang,
    be sure to save your files since you may need to
    kill the browser itself to kill its child processes.
    </para>
  </sect1>

  <sect1 id="ajbrowser-problems">
    <title>Isolating problems running the AspectJ browser</title>

	<para>
	If you have problems with the browser not solved by the documentation,
	please try to see if you have the same problems when running ajc
	directly on the command line.
	</para>
	<itemizedlist>
		<listitem><para>
		If the problem occurs on the command line also, then the problem
		is not in the browser.
		(It may be in the compiler; please send bug reports.)
		</para></listitem>
		<listitem><para>
		If the problem does not occur on the command line, then it may
		lie in the parameters you are supplying in the build options.
		</para></listitem>
		<listitem><para>
		If the build options look correct and the problem only occurs
		when building from the browser, then please submit a bug report.
		</para></listitem>
	</itemizedlist>

	<sect2 id="ajbrowser-knownProblems">
	    <title>Known issues with the AspectJ browser</title>
		<para>
		For the most up-to-date information on known problems,
		see the
		<ulink url="http://bugs.eclipse.org/bugs">bug database</ulink>
		for unresolved
		<ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?&amp;product=AspectJ&amp;component=Compiler&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED">
			compiler bugs
			</ulink> or
		<ulink url="http://bugs.eclipse.org/bugs/buglist.cgi?&amp;product=AspectJ&amp;component=IDE&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED">
			IDE bugs
			</ulink>.
		</para>
		<para>
		<itemizedlist>
		<listitem><para>
	    Memory and forking: Users email most about the browser task running
	    out of memory.
	    This is not a problem with the browser; some compiles take a lot of
	    memory, often more than similar compiles using javac.
	    The browser does not support forking, so the only solution is to
	    edit the java command line or script that launches the browser
	    to add memory.
		</para></listitem>
		<listitem><para>
		Editing build configuration files: this is not currently supported.
		</para></listitem>
		<listitem><para>
		The structure model is incomplete after incremental compiles.
		To get a complete structure model requires a full build.
		</para></listitem>
		<listitem><para>
		If you change the output directory, you must do a
		full build.
		</para></listitem>
		</itemizedlist>
		</para>
	</sect2>
	<sect2 id="ajbrowser-limitations">
		<title>Limitations</title>
		<para>
		<itemizedlist>
		<listitem><para>
		The AJBrowser expects the package and directory structure to match.  If they do not
		it will be unable to browse to the corresponding file.
		</para></listitem>
		<listitem><para>
		The "Run" feature launches applications in the same VM.  As a result, if a Swing application
		is disposed the AJBrowser will be disposed as well.
		</para></listitem>
		</itemizedlist>
		</para>
	</sect2>
	<sect2 id="ajbrowser-feedback">
		<title>AspectJ Browser questions and bugs</title>
		<para>
        You can send email to
        <ulink url="mailto:aspectj-users@dev.eclipse.org">
        aspectj-users@dev.eclipse.org</ulink>.
        (Do join the list to participate!)
        We also welcome any bug reports, patches, and feature requests;
        you can submit them to the bug database at
        <ulink url="http://bugs.eclipse.org/bugs">
           http://bugs.eclipse.org/bugs</ulink>
        using the AspectJ product and IDE component.
		</para>
	</sect2>
	</sect1>
</chapter>

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