initial version

1 files changed, 2343 insertions, 0 deletions

diff --git a/docs/progGuideDB/examples.xml b/docs/progGuideDB/examples.xml
new file mode 100644
index 000000000..2e6a1715d
--- /dev/null
+++ b/docs/progGuideDB/examples.xml
@@ -0,0 +1,2343 @@
+<chapter id="examples" xreflabel="Examples">
+  <title>Examples</title>
+
+  <sect1><!-- About this Chapter -->
+    <title>About this Chapter</title>
+
+    <para>This chapter consists entirely of examples of AspectJ use.
+
+<!-- ADD THIS IN AGAIN WHEN IT'S TRUE
+      The
+      examples have been chosen because they illustrate common AspectJ usage
+      patterns or techniques. Care has been taken to ensure that they also
+      exhibit good style, in addition to being merely syntactically and
+      semantically correct.
+-->
+</para>
+
+    <para>The examples can be grouped into four categories:</para>
+
+    <simplelist columns="2" type="horiz">
+      <member><emphasis role="bold">technique</emphasis></member>
+      <member>Examples which illustrate how to use one or more features of the
+        language. </member>
+
+      <member><emphasis role="bold">development</emphasis></member>
+      <member>Examples of using AspectJ during the development phase of a
+        project. </member>
+
+      <member><emphasis role="bold">production</emphasis></member>
+      <member>Examples of using AspectJ to provide functionality in an
+        application. </member>
+
+      <member><emphasis role="bold">reusable</emphasis></member>
+      <member>Examples of reuse of aspects and pointcuts.</member>
+    </simplelist>
+
+  </sect1>
+
+
+  <sect1>
+    <title>Obtaining, Compiling and Running the Examples</title>
+
+    <para>The examples source code is part of AspectJ's documentation
+      distribution which may be downloaded from <ulink
+        url="http://aspectj.org/dl">the AspectJ download page</ulink>.</para>
+
+    <para>Compiling most examples should be straightforward. Go the
+      <filename><replaceable>InstallDir</replaceable>/examples</filename>
+      directory, and look for a <filename>.lst</filename> file in one of the
+      example subdirectories. Use the <literal>-arglist</literal> option to
+      <literal>ajc</literal> to compile the example. For instance, to compile
+      the telecom example with billing, type </para>
+
+<programlisting>
+ajc -argfile telecom/billing.lst
+</programlisting>
+
+    <para>To run the examples, your classpath must include the AspectJ run-time
+      Java archive (<literal>aspectjrt.jar</literal>). You may either set
+      the <literal>CLASSPATH</literal> environment variable or use the
+      <literal>-classpath</literal> command line option to the Java
+      interpreter:</para>
+
+<programlisting>
+(In Unix use a : in the CLASSPATH)
+java -classpath ".:<replaceable>InstallDir</replaceable>/lib/aspectjrt.jar" telecom.billingSimulation
+</programlisting>
+
+<programlisting>
+(In Windows use a ; in the CLASSPATH)
+java -classpath ".;<replaceable>InstallDir</replaceable>/lib/aspectjrt.jar" telecom.billingSimulation
+</programlisting>
+
+  </sect1>
+
+
+<!--  ============================================================ -->
+<!--  ============================================================ -->
+
+
+  <sect1>
+    <title>Basic Techniques</title>
+
+    <para>This section presents two basic techniques of using AspectJ, one each
+      from the two fundamental ways of capturing crosscutting concerns: with
+      dynamic join points and advice, and with static introduction. Advice
+      changes an application's behavior. Introduction changes both an
+      application's behavior and its structure. </para>
+
+    <para>The first example, <xref endterm="sec:JoinPointsAndtjp:title"
+            linkend="sec:JoinPointsAndtjp"/>, is about gathering and using
+      information about the join point that has triggered some advice. The
+      second example, <xref endterm="sec:RolesAndViews:title"
+            linkend="sec:RolesAndViews"/>, concerns changing an existing class
+      hierarchy. </para>
+
+<!--  ======================================== -->
+
+    <sect2 id="sec:JoinPointsAndtjp"><!-- Join Points and thisJoinPoint -->
+      <title>Join Points and <literal>thisJoinPoint</literal></title>
+        <titleabbrev id="sec:JoinPointsAndtjp:title">Join Points and
+          <literal>thisJoinPoint</literal></titleabbrev>
+
+      <para>(The code for this example is in
+      <filename><replaceable>InstallDir</replaceable>/examples/tjp</filename>.)</para>
+
+      <para>A join point is some point in the
+        execution of a program together with a view into the execution context
+        when that point occurs. Join points are picked out by pointcuts. When a
+        join point is reached, before, after or around advice on that join
+        point may be run. </para>
+
+      <para>When dealing with pointcuts that pick out join points of specific
+      method calls, field gets, or the like, the advice will know exactly what
+      kind of join point it is executing under.  It might even have access to
+      context given by its pointcut.  Here, for example, since the only join
+      points reached will be calls of a certain method, we can get the target
+      and one of the args of the method directly.
+      </para>
+
+<programlisting><![CDATA[
+before(Point p, int x): target(p)
+                     && args(x)
+                     && call(void setX(int)) {
+    if (!p.assertX(x)) {
+        System.out.println("Illegal value for x"); return;
+    }
+}
+]]></programlisting>
+
+   <para>But sometimes the join point is not so clear.  For
+        instance, suppose a complex application is being debugged, and one
+        would like to know when any method in some class is being executed.
+        Then, the pointcut </para>
+
+<programlisting><![CDATA[
+pointcut execsInProblemClass(): within(ProblemClass)
+                             && execution(* *(..));
+]]></programlisting>
+
+      <para>will select all join points where a method defined within the class
+        <classname>ProblemClass</classname> is being executed. But advice
+        executes when a particular join point is matched, and so the question,
+        "Which join point was matched?" naturally arises.</para>
+
+      <para>Information about the join point that was matched is available to
+        advice through the special variable <varname>thisJoinPoint</varname>,
+        of type <ulink
+        url="../api/org/aspectj/lang/JoinPoint.html"><classname>org.aspectj.lang.JoinPoint</classname></ulink>. This
+        class provides methods that return</para>
+
+      <itemizedlist spacing="compact">
+        <listitem>the kind of join point that was matched
+        </listitem>
+        <listitem>the source location of the current join point
+        </listitem>
+        <listitem>normal, short and long string representations of the
+          current join point</listitem>
+        <listitem>the actual argument(s) to the method or field selected
+          by the current join point </listitem>
+        <listitem>the signature of the method or field selected by the
+            current join point</listitem>
+        <listitem>the target object</listitem>
+        <listitem>the currently executing object</listitem>
+        <listitem>a reference to the static portion of the object
+          representing the current join point.  This is also available through
+          the special variable <varname>thisJoinPointStaticPart</varname>.</listitem>
+
+      </itemizedlist>
+
+      <sect3>
+        <title>The <classname>Demo</classname> class</title>
+
+          <para>The class <classname>tjp.Demo</classname> in
+          <filename>tjp/Demo.java</filename> defines two methods
+            <literal>foo</literal> and <literal>bar</literal> with different
+            parameter lists and return types. Both are called, with suitable
+            arguments, by <classname>Demo</classname>'s <function>go</function>
+            method which was invoked from within its <function>main</function>
+            method. </para>
+
+<programlisting><![CDATA[
+public class Demo {
+
+    static Demo d;
+
+    public static void main(String[] args){
+        new Demo().go();
+    }
+
+    void go(){
+        d = new Demo();
+        d.foo(1,d);
+        System.out.println(d.bar(new Integer(3)));
+    }
+
+    void foo(int i, Object o){
+        System.out.println("Demo.foo(" + i + ", " + o + ")\n");
+    }
+
+
+    String bar (Integer j){
+        System.out.println("Demo.bar(" + j + ")\n");
+        return "Demo.bar(" + j  + ")";
+    }
+
+}
+]]></programlisting>
+
+      </sect3>
+
+      <sect3>
+        <title>The Aspect <literal>GetInfo</literal></title>
+
+        <para>This aspect uses around advice to intercept the execution of
+          methods <literal>foo</literal> and <literal>bar</literal> in
+          <classname>Demo</classname>, and prints out information garnered from
+          <literal>thisJoinPoint</literal> to the console. </para>
+
+        <sect4>
+          <title>Defining the scope of a pointcut</title>
+
+          <para>The pointcut <function>goCut</function> is defined as
+            <literal><![CDATA[cflow(this(Demo)) && execution(void
+              go())]]></literal> so that only executions made in the control
+            flow of <literal>Demo.go</literal> are intercepted. The control
+            flow from the method <literal>go</literal> includes the execution of
+            <literal>go</literal> itself, so the definition of the around
+            advice includes <literal>!execution(* go())</literal> to exclude it
+            from the set of executions advised. </para>
+        </sect4>
+
+        <sect4>
+          <title>Printing the class and method name</title>
+
+          <para>The name of the method and that method's defining class are
+            available as parts of the <ulink
+              url="../api/org/aspectj/lang/Signature.html">Signature</ulink>,
+            found using the method <literal>getSignature</literal> of either
+            <literal>thisJoinPoint</literal> or
+            <literal>thisJoinPointStaticPart</literal>. </para>
+
+<programlisting><![CDATA[
+aspect GetInfo {
+
+   static final void println(String s){ System.out.println(s); }
+
+   pointcut goCut(): cflow(this(Demo) && execution(void go()));
+
+   pointcut demoExecs(): within(Demo) && execution(* *(..));
+
+   Object around(): demoExecs() && !execution(* go()) && goCut() {
+      println("Intercepted message: " +
+          thisJoinPointStaticPart.getSignature().getName());
+      println("in class: " +
+          thisJoinPointStaticPart.getSignature().getDeclaringType().getName());
+      printParameters(thisJoinPoint);
+      println("Running original method: \n" );
+      Object result = proceed();
+      println("  result: " + result );
+      return result;
+   }
+
+   static private void printParameters(JoinPoint jp) {
+      println("Arguments: " );
+      Object[] args = jp.getArgs();
+      String[] names = ((CodeSignature)jp.getSignature()).getParameterNames();
+      Class[] types = ((CodeSignature)jp.getSignature()).getParameterTypes();
+      for (int i = 0; i < args.length; i++) {
+         println("  "  + i + ". " + names[i] +
+             " : " +            types[i].getName() +
+             " = " +            args[i]);
+      }
+   }
+}
+]]></programlisting>
+        </sect4>
+
+        <sect4>
+          <title>Printing the parameters</title>
+
+          <para>
+            The static portions of the parameter details, the name and
+            types of the parameters, can be accessed through the <ulink
+              url="../api/org/aspectj/lang/reflect/CodeSignature.html"><literal>CodeSignature</literal></ulink>
+            associated with the join point. All execution join points have code
+            signatures, so the cast to <literal>CodeSignature</literal>
+            cannot fail. </para>
+
+          <para>
+            The dynamic portions of the parameter details, the actual
+            values of the parameters, are accessed directly from the execution
+            join point object. </para>
+        </sect4>
+      </sect3>
+    </sect2>
+
+    <sect2 id="sec:RolesAndViews">
+      <title>Roles and Views Using Introduction</title>
+      <titleabbrev id="sec:RolesAndViews:title">Roles and Views Using
+        Introduction</titleabbrev>
+
+      <para>(The code for this example is in
+      <filename><replaceable>InstallDir</replaceable>/examples/introduction</filename>.)</para>
+
+      <para>Like advice, pieces of introduction are members of an aspect. They
+        define new members that act as if they were defined on another
+        class. Unlike advice, introduction affects not only the behavior of the
+        application, but also the structural relationship between an
+        application's classes. </para>
+
+      <para>This is crucial: Affecting the class structure of an application at
+        makes these modifications available to other components of the
+        application.</para>
+
+      <para>Introduction modifies a class by adding or changing</para>
+      <itemizedlist spacing="compact">
+        <listitem>member fields</listitem>
+        <listitem>member methods</listitem>
+        <listitem>nested classes</listitem>
+      </itemizedlist>
+
+      <para>and by making the class</para>
+
+      <itemizedlist spacing="compact">
+        <listitem>implement interfaces</listitem>
+        <listitem>extend classes</listitem>
+      </itemizedlist>
+
+      <para>
+        This example provides three illustrations of the use of introduction to
+        encapsulate roles or views of a class. The class we will be introducing
+        into, <classname>Point</classname>, is a simple class with rectangular
+        and polar coordinates. Our introduction will make the class
+        <classname>Point</classname>, in turn, cloneable, hashable, and
+        comparable. These facilities are provided by introduction forms without
+        having to modify the class <classname>Point</classname>.
+        </para>
+
+      <sect3>
+        <title>The class <classname>Point</classname></title>
+
+        <para>The class <classname>Point</classname> defines geometric points
+          whose interface includes polar and rectangular coordinates, plus some
+          simple operations to relocate points. <classname>Point</classname>'s
+          implementation has attributes for both its polar and rectangular
+          coordinates, plus flags to indicate which currently reflect the
+          position of the point. Some operations cause the polar coordinates to
+          be updated from the rectangular, and some have the opposite effect.
+          This implementation, which is in intended to give the minimum number
+          of conversions between coordinate systems, has the property that not
+          all the attributes stored in a <classname>Point</classname> object
+          are necessary to give a canonical representation such as might be
+          used for storing, comparing, cloning or making hash codes from
+          points. Thus the aspects, though simple, are not totally trivial.
+        </para>
+
+        <para>
+          The diagram below gives an overview of the aspects and their
+          interaction with the class <classname>Point</classname>.</para>
+
+        <para>
+          <inlinemediaobject>
+            <imageobject>
+              <imagedata fileref="aspects.gif"/>
+            </imageobject>
+          </inlinemediaobject>
+        </para>
+        <para></para>
+
+      </sect3>
+
+      <sect3>
+        <title>Making <classname>Point</classname>s Cloneable &mdash; The Aspect
+          <classname>CloneablePoint</classname></title>
+
+        <para>This first example demonstrates the introduction of a interface
+          (<classname>Cloneable</classname>) and a method
+          (<function>clone</function>) into the class
+          <classname>Point</classname>. In Java, all objects inherit the method
+          <literal>clone</literal> from the class
+          <classname>Object</classname>, but an object is not cloneable unless
+          its class also implements the interface
+          <classname>Cloneable</classname>. In addition, classes frequently
+          have requirements over and above the simple bit-for-bit copying that
+          <literal>Object.clone</literal> does. In our case, we want to update
+          a <classname>Point</classname>'s coordinate systems before we
+          actually clone the <classname>Point</classname>. So we have to
+          override <literal>Object.clone</literal> with a new method that does
+          what we want. </para>
+
+        <para>The <classname>CloneablePoint</classname> aspect uses the
+          <literal>declare parents</literal> form to introduce the interface
+          <classname>Cloneable</classname> into the class
+          <classname>Point</classname>. It then defines a method,
+          <literal>Point.clone</literal>, which overrides the method
+          <function>clone</function> that was inherited from
+          <classname>Object</classname>. <function>Point.clone</function>
+          updates the <classname>Point</classname>'s coordinate systems before
+          invoking its superclass' <function>clone</function> method.</para>
+
+        <programlisting><![CDATA[
+public aspect CloneablePoint {
+
+   declare parents: Point implements Cloneable;
+
+   public Object Point.clone() throws CloneNotSupportedException {
+      // we choose to bring all fields up to date before cloning.
+      makeRectangular();
+      makePolar();
+      return super.clone();
+   }
+
+   public static void main(String[] args){
+      Point p1 = new Point();
+      Point p2 = null;
+
+      p1.setPolar(Math.PI, 1.0);
+      try {
+         p2 = (Point)p1.clone();
+      } catch (CloneNotSupportedException e) {}
+      System.out.println("p1 =" + p1 );
+      System.out.println("p2 =" + p2 );
+
+      p1.rotate(Math.PI / -2);
+      System.out.println("p1 =" + p1 );
+      System.out.println("p2 =" + p2 );
+   }
+}
+]]></programlisting>
+
+        <para>Note that since aspects define types just as classes define
+          types, we can define a <function>main</function> method that is
+          invocable from the command line to use as a test method.</para>
+      </sect3>
+
+      <sect3>
+        <title>Making <classname>Point</classname>s Comparable &mdash; The
+          Aspect <classname>ComparablePoint</classname></title>
+
+        <para>This second example introduces another interface and
+          method into the class <classname>Point</classname>.</para>
+
+        <para>The interface <classname>Comparable</classname> defines the
+          single method <literal>compareTo</literal> which can be use to define
+          a natural ordering relation among the objects of a class that
+          implement it. </para>
+
+        <para>The aspect <classname>ComparablePoint</classname> introduces
+          implements <classname>Comparable</classname> into
+          <classname>Point</classname> along with a
+          <literal>compareTo</literal> method that can be used to compare
+          <classname>Point</classname>s. A <classname>Point</classname>
+          <literal>p1</literal> is  said to be less than
+          another <classname>Point</classname><literal> p2</literal> if
+          <literal>p1</literal> is closer to the origin. </para>
+
+        <programlisting><![CDATA[
+public aspect ComparablePoint {
+
+   declare parents: Point implements Comparable;
+
+   public int Point.compareTo(Object o) {
+      return (int) (this.getRho() - ((Point)o).getRho());
+   }
+
+   public static void main(String[] args){
+      Point p1 = new Point();
+      Point p2 = new Point();
+
+      System.out.println("p1 =?= p2 :" + p1.compareTo(p2));
+
+      p1.setRectangular(2,5);
+      p2.setRectangular(2,5);
+      System.out.println("p1 =?= p2 :" + p1.compareTo(p2));
+
+      p2.setRectangular(3,6);
+      System.out.println("p1 =?= p2 :" + p1.compareTo(p2));
+
+      p1.setPolar(Math.PI, 4);
+      p2.setPolar(Math.PI, 4);
+      System.out.println("p1 =?= p2 :" + p1.compareTo(p2));
+
+      p1.rotate(Math.PI / 4.0);
+      System.out.println("p1 =?= p2 :" + p1.compareTo(p2));
+
+      p1.offset(1,1);
+      System.out.println("p1 =?= p2 :" + p1.compareTo(p2));
+   }
+}]]></programlisting>
+      </sect3>
+
+      <sect3>
+        <title>Making <classname>Point</classname>s Hashable &mdash; The Aspect
+          <classname>HashablePoint</classname></title>
+
+        <para>The third aspect overrides two previously defined methods to
+          give to <classname>Point</classname> the hashing behavior we
+          want.</para>
+
+        <para>The method <literal>Object.hashCode</literal> returns an unique
+          integer, suitable for use as a hash table key. Different
+          implementations are allowed return different integers, but must
+          return distinct integers for distinct objects, and the same integer
+          for objects that test equal. But since the default implementation
+          of <literal>Object.equal</literal> returns <literal>true</literal>
+          only when two objects are identical, we need to redefine both
+          <function>equals</function> and <function>hashCode</function> to work
+          correctly with objects of type <classname>Point</classname>. For
+          example, we want two <classname>Point</classname> objects to test
+          equal when they have the same <literal>x</literal> and
+          <literal>y</literal> values, or the same <literal>rho</literal> and
+          <literal>theta</literal> values, not just when they refer to the same
+          object. We do this by overriding the methods
+          <literal>equals</literal> and <literal>hashCode</literal> in the
+          class <classname>Point</classname>. </para>
+
+        <para>The class <classname>HashablePoint</classname> introduces the
+          methods <literal>hashCode</literal> and <literal>equals</literal>
+          into the class <classname>Point</classname>. These methods use
+          <classname>Point</classname>'s rectangular coordinates to generate a
+          hash code and to test for equality. The <literal>x</literal> and
+          <literal>y</literal> coordinates are obtained using the appropriate
+          get methods, which ensure the rectangular coordinates are up-to-date
+          before returning their values. </para>
+
+        <programlisting><![CDATA[
+public aspect HashablePoint {
+
+   public int Point.hashCode() {
+      return (int) (getX() + getY() % Integer.MAX_VALUE);
+   }
+
+   public boolean Point.equals(Object o) {
+      if (o == this) { return true; }
+      if (!(o instanceof Point)) { return false; }
+      Point other = (Point)o;
+      return (getX() == other.getX()) && (getY() == other.getY());
+   }
+
+   public static void main(String[] args) {
+      Hashtable h = new Hashtable();
+      Point p1 = new Point();
+
+      p1.setRectangular(10, 10);
+      Point p2 = new Point();
+
+      p2.setRectangular(10, 10);
+
+      System.out.println("p1 = " + p1);
+      System.out.println("p2 = " + p2);
+      System.out.println("p1.hashCode() = " + p1.hashCode());
+      System.out.println("p2.hashCode() = " + p2.hashCode());
+
+      h.put(p1, "P1");
+      System.out.println("Got: " + h.get(p2));
+   }
+}
+]]></programlisting>
+
+        <para> Again, we supply a <literal>main</literal> method in the aspect
+        for testing.
+        </para>
+
+      </sect3>
+
+    </sect2>
+
+  </sect1>
+
+<!--  ============================================================ -->
+<!--  ============================================================ -->
+
+  <sect1>
+    <title>Development Aspects</title>
+
+  <sect2>
+    <title>Tracing Aspects</title>
+
+      <para>(The code for this example is in
+      <filename><replaceable>InstallDir</replaceable>/examples/tracing</filename>.)
+      </para>
+
+    <sect3>
+      <title>Overview</title>
+
+        <para>
+        Writing a class that provides tracing functionality is easy: a couple
+        of functions, a boolean flag for turning tracing on and off, a choice
+        for an output stream, maybe some code for formatting the output---these
+        are all elements that <classname>Trace</classname> classes have been
+        known to have. <classname>Trace</classname> classes may be highly
+        sophisticated, too, if the task of tracing the execution of a program
+        demands so.
+      </para>
+
+      <para>
+        But developing the support for tracing is just one part of the effort
+        of inserting tracing into a program, and, most likely, not the biggest
+        part. The other part of the effort is calling the tracing functions at
+        appropriate times. In large systems, this interaction with the tracing
+        support can be overwhelming.  Plus, tracing is one of those things that
+        slows the system down, so these calls should often be pulled out of the
+        system before the product is shipped. For these reasons, it is not
+        unusual for developers to write ad-hoc scripting programs that rewrite
+        the source code by inserting/deleting trace calls before and after the
+        method bodies.
+      </para>
+
+      <para>
+        AspectJ can be used for some of these tracing concerns in a less ad-hoc
+        way.  Tracing can be seen as a concern that crosscuts the entire system
+        and as such is amenable to encapsulation in an aspect.  In addition, it
+        is fairly independent of what the system is doing. Therefore tracing is
+        one of those kind of system aspects that can potentially be plugged in
+        and unplugged without any side-effects in the basic functionality of
+        the system.
+      </para>
+    </sect3>
+
+    <sect3>
+      <title>An Example Application</title>
+
+      <para>
+        Throughout this example we will use a simple application that contains
+        only four classes. The application is about shapes. The
+        <classname>TwoDShape</classname> class is the root of the shape
+        hierarchy:
+      </para>
+
+<programlisting><![CDATA[
+public abstract class TwoDShape {
+    protected double x, y;
+    protected TwoDShape(double x, double y) {
+        this.x = x; this.y = y;
+    }
+    public double getX() { return x; }
+    public double getY() { return y; }
+    public double distance(TwoDShape s) {
+        double dx = Math.abs(s.getX() - x);
+        double dy = Math.abs(s.getY() - y);
+        return Math.sqrt(dx*dx + dy*dy);
+    }
+    public abstract double perimeter();
+    public abstract double area();
+    public String toString() {
+        return (" @ (" + String.valueOf(x) + ", " + String.valueOf(y) + ") ");
+    }
+}
+]]></programlisting>
+
+      <para>
+        <classname>TwoDShape</classname> has two subclasses,
+        <classname>Circle</classname> and <classname>Square</classname>:
+      </para>
+
+<programlisting><![CDATA[
+public class Circle extends TwoDShape {
+    protected double r;
+    public Circle(double x, double y, double r) {
+        super(x, y); this.r = r;
+    }
+    public Circle(double x, double y) { this(  x,   y, 1.0); }
+    public Circle(double r)           { this(0.0, 0.0,   r); }
+    public Circle()                   { this(0.0, 0.0, 1.0); }
+    public double perimeter() {
+        return 2 * Math.PI * r;
+    }
+    public double area() {
+        return Math.PI * r*r;
+    }
+    public String toString() {
+        return ("Circle radius = " + String.valueOf(r) + super.toString());
+    }
+}
+]]></programlisting>
+
+<programlisting><![CDATA[
+public class Square extends TwoDShape {
+    protected double s;    // side
+    public Square(double x, double y, double s) {
+        super(x, y); this.s = s;
+    }
+    public Square(double x, double y) { this(  x,   y, 1.0); }
+    public Square(double s)           { this(0.0, 0.0,   s); }
+    public Square()                   { this(0.0, 0.0, 1.0); }
+    public double perimeter() {
+        return 4 * s;
+    }
+    public double area() {
+        return s*s;
+    }
+    public String toString() {
+        return ("Square side = " + String.valueOf(s) + super.toString());
+    }
+}
+]]></programlisting>
+
+      <para>
+        To run this application, compile the classes. You can do it with or
+        without ajc, the AspectJ compiler. If you've installed AspectJ, go to
+        the directory
+        <filename><replaceable>InstallDir</replaceable>/examples</filename> and
+        type:
+      </para>
+
+<programlisting>
+ajc -argfile tracing/notrace.lst
+</programlisting>
+
+      <para>To run the program, type</para>
+
+<programlisting>
+java tracing.ExampleMain
+</programlisting>
+
+      <para>(we don't need anything special on the classpath since this is pure
+      Java code).  You should see the following output:</para>
+
+<programlisting><![CDATA[
+c1.perimeter() = 12.566370614359172
+c1.area() = 12.566370614359172
+s1.perimeter() = 4.0
+s1.area() = 1.0
+c2.distance(c1) = 4.242640687119285
+s1.distance(c1) = 2.23606797749979
+s1.toString(): Square side = 1.0 @ (1.0, 2.0)
+]]></programlisting>
+
+      </sect3>
+    <sect3>
+      <title>Tracing&mdash;Version 1</title>
+
+      <para>
+        In a first attempt to insert tracing in this application, we will start
+        by writing a <classname>Trace</classname> class that is exactly what we
+        would write if we didn't have aspects.  The implementation is in
+        <filename>version1/Trace.java</filename>.  Its public interface is:
+      </para>
+
+<programlisting><![CDATA[
+public class Trace {
+    public static int TRACELEVEL = 0;
+    public static void initStream(PrintStream s) {...}
+    public static void traceEntry(String str) {...}
+    public static void traceExit(String str) {...}
+}
+]]></programlisting>
+
+      <para>
+        If we didn't have AspectJ, we would have to insert calls to
+        <literal>traceEntry</literal> and <literal>traceExit</literal> in all
+        methods and constructors we wanted to trace, and to initialize
+        <literal>TRACELEVEL</literal> and the stream. If we wanted to trace all
+        the methods and constructors in our example, that would amount to
+        around 40 calls, and we would hope we had not forgotten any method. But
+        we can do that more consistently and reliably with the following
+        aspect (found in <filename>version1/TraceMyClasses.java</filename>):
+      </para>
+
+<programlisting><![CDATA[
+aspect TraceMyClasses {
+    pointcut myClass(): within(TwoDShape) || within(Circle) || within(Square);
+    pointcut myConstructor(): myClass() && execution(new(..));
+    pointcut myMethod(): myClass() && execution(* *(..));
+
+    before (): myConstructor() {
+        Trace.traceEntry("" + thisJoinPointStaticPart.getSignature());
+    }
+    after(): myConstructor() {
+        Trace.traceExit("" + thisJoinPointStaticPart.getSignature());
+    }
+
+    before (): myMethod() {
+        Trace.traceEntry("" + thisJoinPointStaticPart.getSignature());
+    }
+    after(): myMethod() {
+        Trace.traceExit("" + thisJoinPointStaticPart.getSignature());
+    }
+}]]></programlisting>
+
+      <para>
+        This aspect performs the tracing calls at appropriate times. According
+        to this aspect, tracing is performed at the entrance and exit of every
+        method and constructor defined within the shape hierarchy.
+      </para>
+
+      <para>
+        What is printed at before and after each of the traced
+        join points is the signature of the method executing. Since the
+        signature is static information, we can get it through
+        <literal>thisJoinPointStaticPart</literal>.
+      </para>
+
+      <para>
+        To run this version of tracing, go to the directory
+        <filename><replaceable>InstallDir</replaceable>/examples</filename> and
+        type:
+      </para>
+
+<programlisting><![CDATA[
+  ajc -argfile tracing/tracev1.lst
+]]></programlisting>
+
+      <para>
+        Running the main method of
+        <classname>tracing.version1.TraceMyClasses</classname> should produce
+        the output:
+      </para>
+
+<programlisting><![CDATA[
+  --> tracing.TwoDShape(double, double)
+  <-- tracing.TwoDShape(double, double)
+  --> tracing.Circle(double, double, double)
+  <-- tracing.Circle(double, double, double)
+  --> tracing.TwoDShape(double, double)
+  <-- tracing.TwoDShape(double, double)
+  --> tracing.Circle(double, double, double)
+  <-- tracing.Circle(double, double, double)
+  --> tracing.Circle(double)
+  <-- tracing.Circle(double)
+  --> tracing.TwoDShape(double, double)
+  <-- tracing.TwoDShape(double, double)
+  --> tracing.Square(double, double, double)
+  <-- tracing.Square(double, double, double)
+  --> tracing.Square(double, double)
+  <-- tracing.Square(double, double)
+  --> double tracing.Circle.perimeter()
+  <-- double tracing.Circle.perimeter()
+c1.perimeter() = 12.566370614359172
+  --> double tracing.Circle.area()
+  <-- double tracing.Circle.area()
+c1.area() = 12.566370614359172
+  --> double tracing.Square.perimeter()
+  <-- double tracing.Square.perimeter()
+s1.perimeter() = 4.0
+  --> double tracing.Square.area()
+  <-- double tracing.Square.area()
+s1.area() = 1.0
+  --> double tracing.TwoDShape.distance(TwoDShape)
+    --> double tracing.TwoDShape.getX()
+    <-- double tracing.TwoDShape.getX()
+    --> double tracing.TwoDShape.getY()
+    <-- double tracing.TwoDShape.getY()
+  <-- double tracing.TwoDShape.distance(TwoDShape)
+c2.distance(c1) = 4.242640687119285
+  --> double tracing.TwoDShape.distance(TwoDShape)
+    --> double tracing.TwoDShape.getX()
+    <-- double tracing.TwoDShape.getX()
+    --> double tracing.TwoDShape.getY()
+    <-- double tracing.TwoDShape.getY()
+  <-- double tracing.TwoDShape.distance(TwoDShape)
+s1.distance(c1) = 2.23606797749979
+  --> String tracing.Square.toString()
+    --> String tracing.TwoDShape.toString()
+    <-- String tracing.TwoDShape.toString()
+  <-- String tracing.Square.toString()
+s1.toString(): Square side = 1.0 @ (1.0, 2.0)
+]]></programlisting>
+
+      <para>
+        When <filename>TraceMyClasses.java</filename> is not provided to
+        <command>ajc</command>, the aspect does not have any affect on the
+        system and the tracing is unplugged.
+      </para>
+    </sect3>
+
+    <sect3>
+      <title>Tracing&mdash;Version 2</title>
+
+      <para>
+        Another way to accomplish the same thing would be to write a reusable
+        tracing aspect that can be used not only for these application classes,
+        but for any class. One way to do this is to merge the tracing
+        functionality of <literal>Trace&mdash;version1</literal> with the
+        crosscutting support of
+        <literal>TraceMyClasses&mdash;version1</literal>. We end up with a
+        <literal>Trace</literal> aspect (found in
+        <filename>version2/Trace.java</filename>) with the following public
+        interface
+      </para>
+
+<programlisting><![CDATA[
+abstract aspect Trace {
+
+    public static int TRACELEVEL = 2;
+    public static void initStream(PrintStream s) {...}
+    protected static void traceEntry(String str) {...}
+    protected static void traceExit(String str) {...}
+    abstract pointcut myClass();
+}
+]]></programlisting>
+
+      <para>
+        In order to use it, we need to define our own subclass that knows about
+        our application classes, in <filename>version2/TraceMyClasses.java</filename>:
+      </para>
+
+<programlisting><![CDATA[
+public aspect TraceMyClasses extends Trace {
+    pointcut myClass(): within(TwoDShape) || within(Circle) || within(Square);
+
+    public static void main(String[] args) {
+        Trace.TRACELEVEL = 2;
+        Trace.initStream(System.err);
+        ExampleMain.main(args);
+    }
+}
+]]></programlisting>
+
+      <para>
+        Notice that we've simply made the pointcut <literal>classes</literal>,
+        that was an abstract pointcut in the super-aspect, concrete. To run
+        this version of tracing, go to the directory
+        <filename>examples</filename> and type:
+      </para>
+
+<programlisting><![CDATA[
+  ajc -argfile tracing/tracev2.lst
+]]></programlisting>
+
+      <para>
+        The file tracev2.lst lists the application classes as well as this
+        version of the files Trace.java and TraceMyClasses.java. Running the
+        main method of <classname>tracing.version2.TraceMyClasses</classname>
+        should output exactly the same trace information as that from version
+        1.
+      </para>
+
+      <para>
+        The entire implementation of the new <classname>Trace</classname> class
+        is:
+      </para>
+
+<programlisting><![CDATA[
+abstract aspect Trace {
+
+    // implementation part
+
+    public static int TRACELEVEL = 2;
+    protected static PrintStream stream = System.err;
+    protected static int callDepth = 0;
+
+    public static void initStream(PrintStream s) {
+        stream = s;
+    }
+    protected static void traceEntry(String str) {
+        if (TRACELEVEL == 0) return;
+        if (TRACELEVEL == 2) callDepth++;
+        printEntering(str);
+    }
+    protected static void traceExit(String str) {
+        if (TRACELEVEL == 0) return;
+        printExiting(str);
+        if (TRACELEVEL == 2) callDepth--;
+    }
+    private static void printEntering(String str) {
+        printIndent();
+        stream.println("--> " + str);
+    }
+    private static void printExiting(String str) {
+        printIndent();
+        stream.println("<-- " + str);
+    }
+    private static void printIndent() {
+        for (int i = 0; i < callDepth; i++)
+            stream.print("  ");
+    }
+
+    // protocol part
+
+    abstract pointcut myClass();
+
+    pointcut myConstructor(): myClass() && execution(new(..));
+    pointcut myMethod(): myClass() && execution(* *(..));
+
+    before(): myConstructor() {
+        traceEntry("" + thisJoinPointStaticPart.getSignature());
+    }
+    after(): myConstructor() {
+        traceExit("" + thisJoinPointStaticPart.getSignature());
+    }
+
+    before(): myMethod() {
+        traceEntry("" + thisJoinPointStaticPart.getSignature());
+    }
+    after(): myMethod() {
+        traceExit("" + thisJoinPointStaticPart.getSignature());
+    }
+}
+]]></programlisting>
+
+      <para>
+        This version differs from version 1 in several subtle ways. The first
+        thing to notice is that this <classname>Trace</classname> class merges
+        the functional part of tracing with the crosscutting of the tracing
+        calls. That is, in version 1, there was a sharp separation between the
+        tracing support (the class <classname>Trace</classname>) and the
+        crosscutting usage of it (by the class
+        <classname>TraceMyClasses</classname>). In this version those two
+        things are merged. That's why the description of this class explicitly
+        says that "Trace messages are printed before and after constructors and
+        methods are," which is what we wanted in the first place. That is, the
+        placement of the calls, in this version, is established by the aspect
+        class itself, leaving less opportunity for misplacing calls.</para>
+
+      <para>
+        A consequence of this is that there is no need for providing traceEntry
+        and traceExit as public operations of this class. You can see that they
+        were classified as protected. They are supposed to be internal
+        implementation details of the advice.
+      </para>
+
+      <para>
+        The key piece of this aspect is the abstract pointcut classes that
+        serves as the base for the definition of the pointcuts constructors and
+        methods. Even though <classname>classes</classname> is abstract, and
+        therefore no concrete classes are mentioned, we can put advice on it,
+        as well as on the pointcuts that are based on it. The idea is "we don't
+        know exactly what the pointcut will be, but when we do, here's what we
+        want to do with it." In some ways, abstract pointcuts are similar to
+        abstract methods. Abstract methods don't provide the implementation,
+        but you know that the concrete subclasses will, so you can invoke those
+        methods.
+      </para>
+    </sect3>
+    </sect2>
+  </sect1>
+
+<!--  ============================================================ -->
+<!--  ============================================================ -->
+
+  <sect1>
+    <title>Production Aspects</title>
+
+    <!--  ==================== -->
+
+  <sect2><!-- A Bean Aspect -->
+    <title>A Bean Aspect</title>
+
+      <para>(The code for this example is in
+      <filename><replaceable>InstallDir</replaceable>/examples/bean</filename>.)
+      </para>
+
+    <para>
+      This example examines an aspect that makes Point objects into a Java beans
+      with bound properties. </para>
+
+    <sect3>
+      <title>Introduction</title>
+      <para>
+        Java beans are reusable software components that can be visually
+        manipulated in a builder tool. The requirements for an object to be a
+        bean are few. Beans must define a no-argument constructor and must be
+        either <classname>Serializable</classname> or
+        <classname>Externalizable</classname>. Any properties of the object
+        that are to be treated as bean properties should be indicated by the
+        presence of appropriate <literal>get</literal> and
+        <literal>set</literal> methods whose names are
+            <literal>get</literal><emphasis>property</emphasis> and
+            <literal>set </literal><emphasis>property</emphasis>
+        where <emphasis>property</emphasis> is the name of a field in the bean
+        class. Some bean properties, known as bound properties, fire events
+        whenever their values change so that any registered listeners (such as,
+        other beans) will be informed of those changes. Making a bound property
+        involves keeping a list of registered listeners, and creating and
+        dispatching event objects in methods that change the property values,
+        such as set<emphasis>property</emphasis> methods.</para>
+
+      <para>
+        <classname>Point</classname> is a simple class representing points with
+        rectangular coordinates. <classname>Point</classname> does not know
+        anything about being a bean: there are set methods for
+        <literal>x</literal> and <literal>y</literal> but they do not fire
+        events, and the class is not serializable. Bound is an aspect that
+        makes <classname>Point</classname> a serializable class and makes its
+        <literal>get</literal> and <literal>set</literal> methods support the
+        bound property protocol.
+      </para>
+    </sect3>
+
+    <sect3>
+        <title>The Class <classname>Point</classname></title>
+
+        <para>
+        The class <classname>Point</classname> is a very simple class with
+        trivial getters and setters, and a simple vector offset method.
+      </para>
+
+        <programlisting><![CDATA[
+class Point {
+
+  protected int x = 0;
+  protected int y = 0;
+
+  public int getX() {
+    return x;
+  }
+
+  public int getY() {
+    return y;
+  }
+
+  public void setRectangular(int newX, int newY) {
+    setX(newX);
+    setY(newY);
+  }
+
+  public void setX(int newX) {
+    x = newX;
+  }
+
+  public void setY(int newY) {
+    y = newY;
+  }
+
+  public void offset(int deltaX, int deltaY) {
+    setRectangular(x + deltaX, y + deltaY);
+  }
+
+  public String toString() {
+    return "(" + getX() + ", " + getY() + ")" ;
+  }
+}]]></programlisting>
+
+    </sect3>
+
+    <sect3>
+      <title>The Aspect <classname>BoundPoint</classname></title>
+
+      <para>
+        The aspect <classname>BoundPoint</classname> adds "beanness" to
+        <classname>Point</classname> objects. The first thing it does is
+        privately introduce a reference to an instance of
+        <classname>PropertyChangeSupport</classname> into all
+        <classname>Point</classname> objects. The property change
+        support object must be constructed with a reference to the bean for
+        which it is providing support, so it is initialized by passing it this,
+        an instance of <classname>Point</classname>. The support field is
+        privately introduced, so only the code in the aspect can refer to it.
+      </para>
+
+      <para>
+        Methods for registering and managing listeners for property change
+        events are introduced into <classname>Point</classname> by the
+        introductions. These methods delegate the work to the
+        property change support object.
+      </para>
+
+      <para>
+        The introduction also makes <classname>Point</classname> implement the
+        <classname>Serializable</classname> interface. Implementing
+        <classname>Serializable</classname> does not require any methods to be
+        implemented. Serialization for <classname>Point</classname> objects is
+        provided by the default serialization method.
+      </para>
+
+      <para>
+        The pointcut <function>setters</function> names the
+        <literal>set</literal> methods: reception by a
+        <classname>Point</classname> object of any method whose name begins
+        with '<literal>set</literal>' and takes one parameter. The around
+        advice on <literal>setters()</literal> stores the values
+        of the <literal>X</literal> and <literal>Y</literal> properties, calls
+        the original <literal>set</literal> method and then fires the
+        appropriate property change event according to which set method was
+        called. Note that the call to the method proceed needs to pass along
+        the <literal>Point p</literal>. The rule of thumb is that context that
+        an around advice exposes must be passed forward to continue.
+      </para>
+
+<programlisting><![CDATA[
+aspect BoundPoint {
+  private PropertyChangeSupport Point.support = new PropertyChangeSupport(this);
+
+  public void Point.addPropertyChangeListener(PropertyChangeListener listener){
+    support.addPropertyChangeListener(listener);
+  }
+
+  public void Point.addPropertyChangeListener(String propertyName,
+                                              PropertyChangeListener listener){
+
+    support.addPropertyChangeListener(propertyName, listener);
+  }
+
+  public void Point.removePropertyChangeListener(String propertyName,
+                                                 PropertyChangeListener listener) {
+    support.removePropertyChangeListener(propertyName, listener);
+  }
+
+  public void Point.removePropertyChangeListener(PropertyChangeListener listener) {
+    support.removePropertyChangeListener(listener);
+  }
+
+  public void Point.hasListeners(String propertyName) {
+    support.hasListeners(propertyName);
+  }
+
+  declare parents: Point implements Serializable;
+
+  pointcut setter(Point p): call(void Point.set*(*)) && target(p);
+
+  void around(Point p): setter(p) {
+        String propertyName =
+      thisJoinPointStaticPart.getSignature().getName().substring("set".length());
+        int oldX = p.getX();
+        int oldY = p.getY();
+        proceed(p);
+        if (propertyName.equals("X")){
+      firePropertyChange(p, propertyName, oldX, p.getX());
+        } else {
+      firePropertyChange(p, propertyName, oldY, p.getY());
+        }
+  }
+
+  void firePropertyChange(Point p,
+                          String property,
+                          double oldval,
+                          double newval) {
+        p.support.firePropertyChange(property,
+                                 new Double(oldval),
+                                 new Double(newval));
+  }
+}
+]]></programlisting>
+
+    </sect3>
+
+    <sect3>
+      <title>The Test Program</title>
+
+      <para>
+        The test program registers itself as a property change listener to a
+        <literal>Point</literal> object that it creates and then performs
+        simple manipulation of that point: calling its set methods and the
+        offset method. Then it serializes the point and writes it to a file and
+        then reads it back. The result of saving and restoring the point is that
+        a new point is created.
+      </para>
+
+<programlisting><![CDATA[
+  class Demo implements PropertyChangeListener {
+
+    static final String fileName = "test.tmp";
+
+    public void propertyChange(PropertyChangeEvent e){
+      System.out.println("Property " + e.getPropertyName() + " changed from " +
+         e.getOldValue() + " to " + e.getNewValue() );
+    }
+
+    public static void main(String[] args){
+      Point p1 = new Point();
+      p1.addPropertyChangeListener(new Demo());
+      System.out.println("p1 =" + p1);
+      p1.setRectangular(5,2);
+      System.out.println("p1 =" + p1);
+      p1.setX( 6 );
+      p1.setY( 3 );
+      System.out.println("p1 =" + p1);
+      p1.offset(6,4);
+      System.out.println("p1 =" + p1);
+      save(p1, fileName);
+      Point p2 = (Point) restore(fileName);
+      System.out.println("Had: " + p1);
+      System.out.println("Got: " + p2);
+      }
+    ...
+  }
+]]></programlisting>
+
+    </sect3>
+    <sect3>
+      <title>Compiling and Running the Example</title>
+      <para>To compile and run this example, go to the examples directory and type:
+      </para>
+
+<programlisting><![CDATA[
+ajc -argfile bean/files.lst
+java bean.Demo
+]]></programlisting>
+
+      </sect3>
+    </sect2>
+
+    <!--  ==================== -->
+
+  <sect2><!-- The Subject/Observer Protocol -->
+    <title>The Subject/Observer Protocol</title>
+
+      <para>(The code for this example is in
+      <filename><replaceable>InstallDir</replaceable>/examples/observer</filename>.)
+      </para>
+
+    <para>
+      This demo illustrates how the Subject/Observer design pattern can be
+      coded with aspects. </para>
+
+    <sect3>
+      <title>Overview</title>
+      <para>
+         The demo consists of the following: A colored label is a renderable
+         object that has a color that cycles through a set of colors, and a
+         number that records the number of cycles it has been through. A button
+         is an action item that records when it is clicked.
+      </para>
+
+      <para>
+        With these two kinds of objects, we can build up a Subject/Observer
+        relationship in which colored labels observe the clicks of buttons;
+        that is, where colored labels are the observers and buttons are the
+        subjects.
+      </para>
+
+      <para>
+        The demo is designed and implemented using the Subject/Observer design
+        pattern. The remainder of this example explains the classes and aspects
+        of this demo, and tells you how to run it.
+      </para>
+    </sect3>
+
+    <sect3>
+      <title>Generic Components</title>
+
+      <para>
+        The generic parts of the protocol are the interfaces
+        <classname>Subject</classname> and <classname>Observer</classname>, and
+        the abstract aspect <classname>SubjectObserverProtocol</classname>. The
+        <classname>Subject</classname> interface is simple, containing methods
+        to add, remove, and view <classname>Observer</classname> objects, and a
+        method for getting data about state changes:
+      </para>
+
+<programlisting><![CDATA[
+    interface Subject {
+      void addObserver(Observer obs);
+      void removeObserver(Observer obs);
+      Vector getObservers();
+      Object getData();
+  }
+]]></programlisting>
+
+      <para> The <classname>Observer</classname> interface is just as simple,
+        with methods to set and get <classname>Subject</classname> objects, and
+        a method to call when the subject gets updated.
+      </para>
+
+<programlisting><![CDATA[
+  interface Observer {
+      void setSubject(Subject s);
+      Subject getSubject();
+      void update();
+  }
+]]></programlisting>
+
+      <para>
+        The <classname>SubjectObserverProtocol</classname> aspect contains
+        within it all of the generic parts of the protocol, namely, how to fire
+        the <classname>Observer</classname> objects' update methods when some
+        state changes in a subject.
+      </para>
+
+<programlisting><![CDATA[
+  abstract aspect SubjectObserverProtocol {
+
+      abstract pointcut stateChanges(Subject s);
+
+      after(Subject s): stateChanges(s) {
+          for (int i = 0; i < s.getObservers().size(); i++) {
+              ((Observer)s.getObservers().elementAt(i)).update();
+          }
+      }
+
+      private Vector Subject.observers = new Vector();
+      public void   Subject.addObserver(Observer obs) {
+          observers.addElement(obs);
+          obs.setSubject(this);
+      }
+      public void   Subject.removeObserver(Observer obs) {
+          observers.removeElement(obs);
+          obs.setSubject(null);
+      }
+      public Vector Subject.getObservers() { return observers; }
+
+      private Subject Observer.subject = null;
+      public void     Observer.setSubject(Subject s) { subject = s; }
+      public Subject  Observer.getSubject() { return subject; }
+
+  }
+]]></programlisting>
+
+      <para>
+        Note that this aspect does three things. It define an abstract pointcut
+        that extending aspects can override. It defines advice that should run
+        after the join points of the pointcut. And it introduces state and
+        behavior onto the <classname>Subject</classname> and
+        <classname>Observer</classname> interfaces.
+      </para>
+    </sect3>
+
+    <sect3>
+      <title>Application Classes</title>
+
+      <para> <classname>Button</classname> objects extend
+        <classname>java.awt.Button</classname>, and all they do is make sure
+        the <literal>void click()</literal> method is called whenever a button
+        is clicked.
+      </para>
+
+<programlisting><![CDATA[
+  class Button extends java.awt.Button {
+
+      static final Color  defaultBackgroundColor = Color.gray;
+      static final Color  defaultForegroundColor = Color.black;
+      static final String defaultText = "cycle color";
+
+      Button(Display display) {
+          super();
+          setLabel(defaultText);
+          setBackground(defaultBackgroundColor);
+          setForeground(defaultForegroundColor);
+          addActionListener(new ActionListener() {
+                  public void actionPerformed(ActionEvent e) {
+                      Button.this.click();
+                  }
+              });
+          display.addToFrame(this);
+      }
+
+      public void click() {}
+
+  }
+]]></programlisting>
+
+      <para>
+        Note that this class knows nothing about being a Subject.
+      </para>
+      <para>
+        ColorLabel objects are labels that support the void colorCycle()
+        method. Again, they know nothing about being an observer.
+      </para>
+
+<programlisting><![CDATA[
+  class ColorLabel extends Label {
+
+      ColorLabel(Display display) {
+          super();
+          display.addToFrame(this);
+      }
+
+      final static Color[] colors = {Color.red, Color.blue,
+                                     Color.green, Color.magenta};
+      private int colorIndex = 0;
+      private int cycleCount = 0;
+      void colorCycle() {
+          cycleCount++;
+          colorIndex = (colorIndex + 1) % colors.length;
+          setBackground(colors[colorIndex]);
+          setText("" + cycleCount);
+      }
+  }
+]]></programlisting>
+
+      <para>
+        Finally, the <classname>SubjectObserverProtocolImpl</classname>
+        implements the subject/observer protocol, with
+        <classname>Button</classname> objects as subjects and
+        <classname>ColorLabel</classname> objects as observers:
+      </para>
+
+<programlisting><![CDATA[
+package observer;
+
+import java.util.Vector;
+
+aspect SubjectObserverProtocolImpl extends SubjectObserverProtocol {
+
+    declare parents: Button implements Subject;
+    public Object Button.getData() { return this; }
+
+    declare parents: ColorLabel implements Observer;
+    public void    ColorLabel.update() {
+        colorCycle();
+    }
+
+    pointcut stateChanges(Subject s):
+        target(s) &&
+        call(void Button.click());
+
+}]]></programlisting>
+
+      <para>
+        It does this by introducing the appropriate interfaces onto the
+        <classname>Button</classname> and <classname>ColorLabel</classname>
+        classes, making sure the methods required by the interfaces are
+        implemented, and providing a definition for the
+        <literal>stateChanges</literal> pointcut. Now, every time a
+        <classname>Button</classname> is clicked, all
+        <classname>ColorLabel</classname> objects observing that button will
+        <literal>colorCycle</literal>.
+      </para>
+    </sect3>
+
+    <sect3>
+      <title>Compiling and Running</title>
+
+      <para> <classname>Demo</classname> is the top class that starts this
+        demo. It instantiates a two buttons and three observers and links them
+        together as subjects and observers. So to run the demo, go to the
+        <filename>examples</filename> directory and type:
+      </para>
+
+<programlisting><![CDATA[
+  ajc -argfile observer/files.lst
+  java observer.Demo
+]]></programlisting>
+
+      </sect3>
+    </sect2>
+
+    <!--  ==================== -->
+
+    <sect2>
+    <title>A Simple Telecom Simulation</title>
+
+      <para>(The code for this example is in
+      <filename><replaceable>InstallDir</replaceable>/examples/telecom</filename>.)
+      </para>
+
+    <para>
+      This example illustrates some ways that dependent concerns can be encoded
+      with aspects. It uses an example system comprising a simple model of
+      telephone connections to which timing and billing features are added
+      using aspects, where the billing feature depends upon the timing feature.
+    </para>
+
+    <sect3>
+      <title>The Application</title>
+
+      <para>
+        The example application is a simple simulation of a telephony system in
+        which customers make, accept, merge and hang-up both local and long
+        distance calls. The application architecture is in three layers.
+      </para>
+      <itemizedlist>
+        <listitem>
+          <para>
+            The basic objects  provide basic functionality to simulate
+            customers, calls and connections (regular calls have one
+            connection, conference calls have more than one).
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The timing feature is concerned with timing the connections and
+            keeping the total connection time per customer. Aspects are used to
+            add a timer to each connection and to manage the total time per
+            customer.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The billing feature is concerned with charging customers for the
+            calls they make. Aspects are used to calculate a charge per
+            connection and, upon termination of a connection, to add the charge
+            to the appropriate customer's bill. The billing aspect builds upon
+            the timing aspect: it uses a pointcut defined in Timing and it uses
+            the timers that are associated with connections.
+          </para>
+        </listitem>
+      </itemizedlist>
+      <para>
+        The simulation of system has three configurations: basic, timing and
+        billing. Programs for the three configurations are in classes
+        <classname>BasicSimulation</classname>,
+        <classname>TimingSimulation</classname> and
+        <classname>BillingSimulation</classname>. These share a common
+        superclass <classname>AbstractSimulation</classname>, which defines the
+        method run with the simulation itself and the method wait used to
+        simulate elapsed time.
+      </para>
+    </sect3>
+
+    <sect3>
+      <title>The Basic Objects</title>
+
+      <para>
+        The telecom simulation comprises the classes
+        <classname>Customer</classname>, <classname>Call</classname> and the
+        abstract class <classname>Connection</classname> with its two concrete
+        subclasses <classname>Local</classname> and
+        <classname>LongDistance</classname>. Customers have a name and a
+        numeric area code. They also have methods for managing calls. Simple
+        calls are made between one customer (the caller) and another (the
+        receiver), a <classname>Connection</classname> object is used to
+        connect them. Conference calls between more than two customers will
+        involve more than one connection. A customer may be involved in many
+        calls at one time.
+        <inlinemediaobject>
+          <imageobject>
+            <imagedata fileref="telecom.gif"/>
+          </imageobject>
+        </inlinemediaobject>
+      </para>
+    </sect3>
+
+    <sect3>
+      <title>The Class <classname>Customer</classname></title>
+
+      <para>
+        <classname>Customer</classname> has methods <literal>call</literal>,
+        <literal>pickup</literal>, <literal>hangup</literal> and
+        <literal>merge</literal> for managing calls.
+      </para>
+
+<programlisting><![CDATA[
+public class Customer {
+
+      private String name;
+      private int areacode;
+      private Vector calls = new Vector();
+
+      protected void removeCall(Call c){
+          calls.removeElement(c);
+      }
+
+      protected void addCall(Call c){
+          calls.addElement(c);
+      }
+
+      public Customer(String name, int areacode) {
+          this.name = name;
+          this.areacode = areacode;
+      }
+
+      public String toString() {
+          return name + "(" + areacode + ")";
+      }
+
+      public int getAreacode(){
+          return areacode;
+      }
+
+      public boolean localTo(Customer other){
+          return areacode == other.areacode;
+      }
+
+      public Call call(Customer receiver) {
+          Call call = new Call(this, receiver);
+          addCall(call);
+          return call;
+      }
+
+      public void pickup(Call call) {
+          call.pickup();
+          addCall(call);
+      }
+
+      public void hangup(Call call) {
+          call.hangup(this);
+          removeCall(call);
+      }
+
+      public void merge(Call call1, Call call2){
+          call1.merge(call2);
+          removeCall(call2);
+      }
+  }
+]]></programlisting>
+
+      </sect3>
+
+    <sect3>
+      <title>The Class <classname>Call</classname></title>
+
+      <para>
+        Calls are created with a caller and receiver who are customers. If the
+        caller and receiver have the same area code then the call can be
+        established with a <classname>Local</classname> connection (see below),
+        otherwise a <classname>LongDistance</classname> connection is required.
+        A call comprises a number of connections between customers. Initially
+        there is only the connection between the caller and receiver but
+        additional connections can be added if calls are merged to form
+        conference calls.
+      </para>
+    </sect3>
+
+    <sect3>
+      <title>The Class <classname>Connection</classname></title>
+
+      <para>The class <classname>Connection</classname> models the physical
+        details of establishing a connection between customers. It does this
+        with a simple state machine (connections are initially
+        <literal>PENDING</literal>, then <literal>COMPLETED</literal> and
+        finally <literal>DROPPED</literal>). Messages are printed to the
+        console so that the state of connections can be observed. Connection is
+        an abstract class with two concrete subclasses:
+        <classname>Local</classname> and <classname>LongDistance</classname>.
+      </para>
+
+<programlisting><![CDATA[
+  abstract class Connection {
+
+      public static final int PENDING = 0;
+      public static final int COMPLETE = 1;
+      public static final int DROPPED = 2;
+
+      Customer caller, receiver;
+      private int state = PENDING;
+
+      Connection(Customer a, Customer b) {
+          this.caller = a;
+          this.receiver = b;
+      }
+
+      public int getState(){
+          return state;
+      }
+
+      public Customer getCaller() { return caller; }
+
+      public Customer getReceiver() { return receiver; }
+
+      void complete() {
+          state = COMPLETE;
+          System.out.println("connection completed");
+      }
+
+      void drop() {
+          state = DROPPED;
+          System.out.println("connection dropped");
+      }
+
+      public boolean connects(Customer c){
+          return (caller == c || receiver == c);
+      }
+
+  }
+]]></programlisting>
+
+      </sect3>
+
+    <sect3>
+      <title>The Class Local</title>
+
+<programlisting><![CDATA[
+  class Local extends Connection {
+      Local(Customer a, Customer b) {
+          super(a, b);
+          System.out.println("[new local connection from " +
+             a + " to " + b + "]");
+      }
+  }
+]]></programlisting>
+
+      </sect3>
+
+    <sect3>
+      <title>The Class LongDistance</title>
+
+<programlisting><![CDATA[
+  class LongDistance extends Connection {
+      LongDistance(Customer a, Customer b) {
+          super(a, b);
+          System.out.println("[new long distance connection from " +
+              a + " to " + b + "]");
+      }
+  }
+]]></programlisting>
+
+      </sect3>
+
+    <sect3>
+      <title>Compiling and Running the Basic Simulation</title>
+
+      <para>
+        The source files for the basic system are listed in the file
+        <filename>basic.lst</filename>. To build and run the basic system, in a
+        shell window, type these commands:
+      </para>
+
+<programlisting><![CDATA[
+ajc -argfile telecom/basic.lst
+java telecom.BasicSimulation
+]]></programlisting>
+
+      </sect3>
+
+    <sect3>
+      <title>Timing</title>
+      <para>
+        The <classname>Timing</classname> aspect keeps track of total
+        connection time for each <classname>Customer</classname> by starting
+        and stopping a timer associated with each connection. It uses some
+        helper classes:
+      </para>
+
+      <sect4>
+        <title>The Class <classname>Timer</classname></title>
+
+        <para>
+          A <classname>Timer</classname> object simply records the current time
+          when it is started and stopped, and returns their difference when
+          asked for the elapsed time. The aspect
+          <classname>TimerLog</classname> (below) can be used to cause the
+          start and stop times to be printed to standard output.
+        </para>
+
+<programlisting><![CDATA[
+  class Timer {
+      long startTime, stopTime;
+
+      public void start() {
+          startTime = System.currentTimeMillis();
+          stopTime = startTime;
+      }
+
+      public void stop() {
+          stopTime = System.currentTimeMillis();
+      }
+
+      public long getTime() {
+          return stopTime - startTime;
+      }
+  }
+]]></programlisting>
+
+        </sect4>
+      </sect3>
+
+      <sect3>
+        <title>The Aspect <classname>TimerLog</classname></title>
+
+        <para>
+          The aspect <classname>TimerLog</classname> can be included in a
+          build to get the timer to announce when it is started and stopped.
+        </para>
+
+<programlisting><![CDATA[
+public aspect TimerLog {
+
+    after(Timer t): target(t) && call(* Timer.start())  {
+      System.err.println("Timer started: " + t.startTime);
+    }
+
+    after(Timer t): target(t) && call(* Timer.stop()) {
+      System.err.println("Timer stopped: " + t.stopTime);
+    }
+}
+]]></programlisting>
+
+        </sect3>
+
+      <sect3>
+        <title>The Aspect <classname>Timing</classname></title>
+
+        <para>
+          The aspect <classname>Timing</classname> introduces attribute
+          <literal>totalConnectTime</literal> into the class
+          <classname>Customer</classname> to store the accumulated connection
+          time per <classname>Customer</classname>. It introduces attribute
+          timer into <classname>Connection</classname> to associate a timer
+          with each <classname>Connection</classname>. Two pieces of after
+          advice ensure that the timer is started when a connection is
+          completed and and stopped when it is dropped. The pointcut
+          <literal>endTiming</literal> is defined so that it can be used by the
+          <classname>Billing</classname> aspect.
+        </para>
+
+<programlisting><![CDATA[
+public aspect Timing {
+
+    public long Customer.totalConnectTime = 0;
+
+    public long getTotalConnectTime(Customer cust) {
+        return cust.totalConnectTime;
+    }
+    private Timer Connection.timer = new Timer();
+    public Timer getTimer(Connection conn) { return conn.timer; }
+
+    after (Connection c): target(c) && call(void Connection.complete()) {
+        getTimer(c).start();
+    }
+
+    pointcut endTiming(Connection c): target(c) &&
+        call(void Connection.drop());
+
+    after(Connection c): endTiming(c) {
+        getTimer(c).stop();
+        c.getCaller().totalConnectTime += getTimer(c).getTime();
+        c.getReceiver().totalConnectTime += getTimer(c).getTime();
+    }
+}]]></programlisting>
+
+        </sect3>
+
+    <sect3>
+      <title>Billing</title>
+
+      <para>
+        The Billing system adds billing functionality to the telecom
+        application on top of timing.
+      </para>
+
+      <sect4>
+        <title>The Aspect <classname>Billing</classname></title>
+
+        <para>
+          The aspect <classname>Billing</classname> introduces attribute
+          <literal>payer</literal> into <classname>Connection</classname>
+          to indicate who initiated the call and therefore who is
+          responsible to pay for it. It also introduces method
+          <literal>callRate</literal> into <classname>Connection</classname>
+          so that local and long distance calls can be charged
+          differently. The call charge must be calculated after the timer is
+          stopped; the after advice on pointcut
+          <literal>Timing.endTiming</literal> does this and
+          <classname>Billing</classname> dominates Timing to make
+          sure that this advice runs after <classname>Timing's</classname>
+          advice on the same join point. It introduces attribute
+          <literal>totalCharge</literal> and its associated methods into
+          <classname>Customer</classname> (to manage the
+          customer's bill information.
+        </para>
+
+<programlisting><![CDATA[
+public aspect Billing dominates Timing {
+    // domination required to get advice on endtiming in the right order
+
+    public static final long LOCAL_RATE = 3;
+    public static final long LONG_DISTANCE_RATE = 10;
+
+
+    public Customer Connection.payer;
+    public Customer getPayer(Connection conn) { return conn.payer; }
+
+    after(Customer cust) returning (Connection conn):
+        args(cust, ..) && call(Connection+.new(..)) {
+        conn.payer = cust;
+    }
+
+    public abstract long Connection.callRate();
+
+
+    public long LongDistance.callRate() { return LONG_DISTANCE_RATE; }
+    public long Local.callRate() { return LOCAL_RATE; }
+
+
+    after(Connection conn): Timing.endTiming(conn) {
+        long time = Timing.aspectOf().getTimer(conn).getTime();
+        long rate = conn.callRate();
+        long cost = rate * time;
+        getPayer(conn).addCharge(cost);
+    }
+
+
+    public long Customer.totalCharge = 0;
+    public long getTotalCharge(Customer cust) { return cust.totalCharge; }
+
+    public void Customer.addCharge(long charge){
+        totalCharge += charge;
+    }
+}
+]]></programlisting>
+
+        </sect4>
+    </sect3>
+
+    <sect3>
+      <title>Accessing the Introduced State</title>
+
+      <para>
+        Both the aspects <classname>Timing</classname> and
+        <classname>Billing</classname> contain the definition of operations
+        that the rest of the system may want to access. For example, when
+        running the simulation with one or both aspects, we want to find out
+        how much time each customer spent on the telephone and how big their
+        bill is. That information is also stored in the classes, but they are
+        accessed through static methods of the aspects, since the state they
+        refer to is private to the aspect.
+      </para>
+
+      <para>
+        Take a look at the file <filename>TimingSimulation.java</filename>. The
+        most important method of this class is the method
+        <filename>report(Customer c)</filename>, which is used in the method
+        run of the superclass <classname>AbstractSimulation</classname>. This
+        method is intended to print out the status of the customer, with
+        respect to the <classname>Timing</classname> feature.
+      </para>
+
+<programlisting><![CDATA[
+  protected void report(Customer c){
+      Timing t = Timing.aspectOf();
+      System.out.println(c + " spent " + t.getTotalConnectTime(c));
+  }
+]]></programlisting>
+
+      </sect3>
+
+    <sect3>
+      <title>Compiling and Running</title>
+
+      <para>
+        The files timing.lst and billing.lst contain file lists for the timing
+        and billing configurations. To build and run the application with only
+        the timing feature, go to the directory examples and type:
+      </para>
+
+<programlisting><![CDATA[
+  ajc -argfile telecom/timing.lst
+  java telecom.TimingSimulation
+]]></programlisting>
+
+      <para>
+        To build and run the application with the timing and billing features,
+        go to the directory examples and type:
+      </para>
+
+<programlisting><![CDATA[
+  ajc -argfile telecom/billing.lst
+  java telecom.BillingSimulation
+]]></programlisting>
+
+      </sect3>
+
+    <sect3>
+      <title>Discussion</title>
+
+      <para>
+        There are some explicit dependencies between the aspects Billing and
+        Timing:
+        <itemizedlist>
+          <listitem>
+            <para>
+              Billing is declared to dominate Timing so that Billing's after
+              advice runs after that of Timing  when they are on the same join
+              point.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Billing uses the pointcut Timing.endTiming.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Billing needs access to the timer associated with a connection.
+            </para>
+          </listitem>
+        </itemizedlist>
+      </para>
+    </sect3>
+    </sect2>
+  </sect1>
+
+<!--  ============================================================ -->
+<!--  ============================================================ -->
+
+  <sect1>
+    <title>Reusable Aspects</title>
+
+    <sect2>
+      <title>Tracing Aspects Revisited</title>
+
+      <para>(The code for this example is in
+      <filename><replaceable>InstallDir</replaceable>/examples/tracing</filename>.)
+      </para>
+
+    <sect3>
+      <title>Tracing&mdash;Version 3</title>
+
+      <para>
+        One advantage of not exposing the methods traceEntry and traceExit as
+        public operations is that we can easily change their interface without
+        any dramatic consequences in the rest of the code.
+      </para>
+
+      <para>
+        Consider, again, the program without AspectJ. Suppose, for example,
+        that at some point later the requirements for tracing change, stating
+        that the trace messages should always include the string representation
+        of the object whose methods are being traced. This can be achieved in
+        at least two ways. One way is keep the interface of the methods
+        <literal>traceEntry</literal> and <literal>traceExit</literal> as it
+        was before,
+      </para>
+
+<programlisting><![CDATA[
+  public static void traceEntry(String str);
+  public static void traceExit(String str);
+]]></programlisting>
+
+      <para>
+        In this case, the caller is responsible for ensuring that the string
+        representation of the object is part of the string given as argument.
+        So, calls must look like:
+      </para>
+
+<programlisting><![CDATA[
+  Trace.traceEntry("Square.distance in " + toString());
+]]></programlisting>
+
+      <para>
+        Another way is to enforce the requirement with a second argument in the
+        trace operations, e.g.
+      </para>
+
+<programlisting><![CDATA[
+  public static void traceEntry(String str, Object obj);
+  public static void traceExit(String str, Object obj);
+]]></programlisting>
+
+      <para>
+        In this case, the caller is still responsible for sending the right
+        object, but at least there is some guarantees that some object will be
+        passed. The calls will look like:
+      </para>
+
+<programlisting><![CDATA[
+  Trace.traceEntry("Square.distance", this);
+]]></programlisting>
+
+      <para>
+        In either case, this change to the requirements of tracing will have
+        dramatic consequences in the rest of the code -- every call to the
+        trace operations traceEntry and traceExit must be changed!
+      </para>
+
+      <para>
+        Here's another advantage of doing tracing with an aspect. We've already
+        seen that in version 2 <literal>traceEntry</literal> and
+        <literal>traceExit</literal> are not publicly exposed. So changing
+        their interfaces, or the way they are used, has only a small effect
+        inside the <classname>Trace</classname> class. Here's a partial view at
+        the implementation of <classname>Trace</classname>, version 3. The
+        differences with respect to version 2 are stressed in the
+        comments:
+      </para>
+
+<programlisting><![CDATA[
+abstract aspect Trace {
+
+    public static int TRACELEVEL = 0;
+    protected static PrintStream stream = null;
+    protected static int callDepth = 0;
+
+    public static void initStream(PrintStream s) {
+        stream = s;
+    }
+
+    protected static void traceEntry(String str, Object o) {
+        if (TRACELEVEL == 0) return;
+        if (TRACELEVEL == 2) callDepth++;
+        printEntering(str + ": " + o.toString());
+    }
+
+    protected static void traceExit(String str, Object o) {
+        if (TRACELEVEL == 0) return;
+        printExiting(str + ": " + o.toString());
+        if (TRACELEVEL == 2) callDepth--;
+    }
+
+    private static void printEntering(String str) {
+        printIndent();
+        stream.println("Entering " + str);
+    }
+
+    private static void printExiting(String str) {
+        printIndent();
+        stream.println("Exiting " + str);
+    }
+
+
+    private static void printIndent() {
+        for (int i = 0; i < callDepth; i++)
+            stream.print("  ");
+    }
+
+
+    abstract pointcut myClass(Object obj);
+
+    pointcut myConstructor(Object obj): myClass(obj) && execution(new(..));
+    pointcut myMethod(Object obj): myClass(obj) &&
+        execution(* *(..)) && !execution(String toString());
+
+    before(Object obj): myConstructor(obj) {
+        traceEntry("" + thisJoinPointStaticPart.getSignature(), obj);
+    }
+    after(Object obj): myConstructor(obj) {
+        traceExit("" + thisJoinPointStaticPart.getSignature(), obj);
+    }
+
+    before(Object obj): myMethod(obj) {
+        traceEntry("" + thisJoinPointStaticPart.getSignature(), obj);
+    }
+    after(Object obj): myMethod(obj) {
+        traceExit("" + thisJoinPointStaticPart.getSignature(), obj);
+    }
+}
+]]></programlisting>
+
+      <para>
+        As you can see, we decided to apply the first design by preserving the
+        interface of the methods <literal>traceEntry</literal> and
+        <literal>traceExit</literal>. But it doesn't matter&mdash;we could as
+        easily have applied the second design (the code in the directory
+        <filename>examples/tracing/version3</filename> has the second design).
+        The point is that the effects of this change in the tracing
+        requirements are limited to the <classname>Trace</classname> aspect
+        class.
+      </para>
+
+      <para>
+        One implementation change worth noticing is the specification of the
+        pointcuts. They now expose the object. To maintain full consistency
+        with the behavior of version 2, we should have included tracing for
+        static methods, by defining another pointcut for static methods and
+        advising it. We leave that as an exercise.
+      </para>
+
+      <para>
+        Moreover, we had to exclude the execution join point of the method
+        <filename>toString</filename> from the <literal>methods</literal>
+        pointcut. The problem here is that <literal>toString</literal> is being
+        called from inside the advice.  Therefore if we trace it, we will end
+        up in an infinite recursion of calls. This is a subtle point, and one
+        that you must be aware when writing advice. If the advice calls back to
+        the objects, there is always the possibility of recursion. Keep that in
+        mind!
+      </para>
+
+      <para>
+        In fact, esimply excluding the execution join point may not be enough,
+        if there are calls to other traced methods within it -- in which case,
+        the restriction should be
+      </para>
+      
+<programlisting><![CDATA[
+&& !cflow(execution(String toString()))
+]]></programlisting>
+
+      <para>
+        excluding both the execution of toString methods and all join points
+        under that execution. 
+      </para>
+
+      <para>
+        In summary, to implement the change in the tracing requirements we had
+        to make a couple of changes in the implementation of the
+        <classname>Trace</classname> aspect class, including changing the
+        specification of the pointcuts. That's only natural. But the
+        implementation changes were limited to this aspect. Without aspects, we
+        would have to change the implementation of every application class.
+      </para>
+
+      <para>
+        Finally, to run this version of tracing, go to the directory
+        <filename>examples</filename> and type:
+      </para>
+
+<programlisting><![CDATA[
+ajc -argfile tracing/tracev3.lst
+]]></programlisting>
+
+      <para>
+        The file tracev3.lst lists the application classes as well as this
+        version of the files <filename>Trace.java</filename> and
+        <filename>TraceMyClasses.java</filename>. To run the program, type
+      </para>
+
+<programlisting><![CDATA[
+java tracing.version3.TraceMyClasses
+]]></programlisting>
+
+      <para>The output should be:</para>
+
+<programlisting><![CDATA[
+  --> tracing.TwoDShape(double, double)
+  <-- tracing.TwoDShape(double, double)
+  --> tracing.Circle(double, double, double)
+  <-- tracing.Circle(double, double, double)
+  --> tracing.TwoDShape(double, double)
+  <-- tracing.TwoDShape(double, double)
+  --> tracing.Circle(double, double, double)
+  <-- tracing.Circle(double, double, double)
+  --> tracing.Circle(double)
+  <-- tracing.Circle(double)
+  --> tracing.TwoDShape(double, double)
+  <-- tracing.TwoDShape(double, double)
+  --> tracing.Square(double, double, double)
+  <-- tracing.Square(double, double, double)
+  --> tracing.Square(double, double)
+  <-- tracing.Square(double, double)
+  --> double tracing.Circle.perimeter()
+  <-- double tracing.Circle.perimeter()
+c1.perimeter() = 12.566370614359172
+  --> double tracing.Circle.area()
+  <-- double tracing.Circle.area()
+c1.area() = 12.566370614359172
+  --> double tracing.Square.perimeter()
+  <-- double tracing.Square.perimeter()
+s1.perimeter() = 4.0
+  --> double tracing.Square.area()
+  <-- double tracing.Square.area()
+s1.area() = 1.0
+  --> double tracing.TwoDShape.distance(TwoDShape)
+    --> double tracing.TwoDShape.getX()
+    <-- double tracing.TwoDShape.getX()
+    --> double tracing.TwoDShape.getY()
+    <-- double tracing.TwoDShape.getY()
+  <-- double tracing.TwoDShape.distance(TwoDShape)
+c2.distance(c1) = 4.242640687119285
+  --> double tracing.TwoDShape.distance(TwoDShape)
+    --> double tracing.TwoDShape.getX()
+    <-- double tracing.TwoDShape.getX()
+    --> double tracing.TwoDShape.getY()
+    <-- double tracing.TwoDShape.getY()
+  <-- double tracing.TwoDShape.distance(TwoDShape)
+s1.distance(c1) = 2.23606797749979
+  --> String tracing.Square.toString()
+    --> String tracing.TwoDShape.toString()
+    <-- String tracing.TwoDShape.toString()
+  <-- String tracing.Square.toString()
+s1.toString(): Square side = 1.0 @ (1.0, 2.0)
+]]></programlisting>
+
+      </sect3>
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+Local variables:
+compile-command: "java sax.SAXCount -v progguide.xml && java com.icl.saxon.StyleSheet -w0 progguide.xml progguide.html.xsl"
+fill-column: 79
+sgml-local-ecat-files: "progguide.ced"
+sgml-parent-document:("progguide.xml" "book" "chapter")
+End:
+-->