initial version

1 files changed, 222 insertions, 0 deletions

diff --git a/docs/devGuideDB/ajbrowser.xml b/docs/devGuideDB/ajbrowser.xml
new file mode 100644
index 000000000..f4a44597c
--- /dev/null
+++ b/docs/devGuideDB/ajbrowser.xml
@@ -0,0 +1,222 @@
+<refentry>
+  <refnamediv>
+    <refname>AspectJ Browser</refname>
+
+    <refpurpose>GUI tool for compiling programs with ajc and navigating the
+    crosscutting structure (early-access)</refpurpose>
+
+  </refnamediv>
+
+    <refsect1 id="ajbrowser" xreflabel="AspectJ Browser">
+        <title>Overview</title>
+
+
+        <para>
+            The AspectJ Browser is a development tool that will allow you to
+            compile using ajc, navigate your program's static structure, edit
+            source files, and graphically edit build configuration files.
+        </para>
+
+          <imageobject>
+            <imagedata fileref="ajbrowser-building.gif"/>
+          </imageobject>
+
+        <para>
+            To use the browser launch it by typing "ajbrowser" (assuming that
+            you've followed the instructions for setting up <xref
+            linkend="ajc">ajc</xref>).  You can either pass in one or more
+            ".lst" build configuration files as command line parameters to the
+            browser in order to build them and navigate the corresponding
+            structure, or you can open one or more ".lst" files with "File ->
+            Open" or with the "Open Build Configuration" button
+        (<inlinemediaobject>
+           <imageobject>
+             <imagedata fileref="openConfig.gif"/>
+           </imageobject>
+        </inlinemediaobject>).
+        </para>
+    </refsect1>
+
+  <refsect1>
+    <title>Compiling a 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 also select a
+        different build configuration here, as in label 1.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Navigating the Program Structure</title>
+
+    <para>
+        Select nodes in the program structure by clicking them (as in 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>Manipulating Build Configuration</title>
+
+        <para>
+            Build configurations can be manipulated adding, removing, and
+            editing build configuration files using the corresponding toolbar
+            buttons.  The current configuration can be selected in the
+            configurations listbox.  Build configurations are represented by
+            ".lst" files (which are described in the <xref
+            linkend="ajc">ajc</xref> documentation).
+        </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>
+
+          <imageobject>
+            <imagedata fileref="ajbrowser-options.gif"/>
+          </imageobject>
+
+            </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>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </refsect1>
+</refentry>
+
+<!-- Local variables: -->
+<!-- fill-column: 79 -->
+<!-- sgml-local-ecat-files: devguide.ced -->
+<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") -->
+<!-- End: -->