mirror of
https://github.com/eclipse-aspectj/aspectj.git
synced 2024-09-13 15:45:38 +02:00
5229f8a4a1
- discussed the .ajbrowser file and setting classpath using options - discussed config files separately - added caveat about only displaying static crosscutting
261 lines
10 KiB
XML
261 lines
10 KiB
XML
<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 <ctrl>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 -> 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
|
|
-> 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: -->
|