path: root/docs/progGuideDB/gettingstarted.xml

<chapter id="gettingstarted" xreflabel="Getting Started with AspectJ">

  <title>Getting Started with AspectJ</title>

  <sect1>
    <title>Introduction</title>

    <para>Many software developers are attracted to the idea of aspect-oriented
      programming
      <indexterm>
        <primary>aspect-oriented programming</primary>
      </indexterm>
      (AOP)
      <indexterm>
        <primary>AOP</primary>
        <see> aspect-oriented programming</see>
      </indexterm>
      but unsure about how to begin using the technology. They
      recognize the concept of crosscutting concerns, and know that they have
      had problems with the implementation of such concerns in the past. But
      there are many questions about how to adopt AOP into the development
      process. Common questions include:
      <itemizedlist spacing="compact">
        <listitem>
          <para>Can I use aspects in my existing code?</para>
        </listitem>
        <listitem>
          <para>What kinds of benefits can I expect to get from using aspects?
          </para>
        </listitem>
        <listitem>
          <para>How do I find aspects in my programs?</para>
        </listitem>
        <listitem>
          <para>How steep is the learning curve for AOP?</para>
        </listitem>
        <listitem>
          <para>What are the risks of using this new technology?</para>
        </listitem>
      </itemizedlist></para>

    <para>This chapter addresses these questions in the context of AspectJ a
      general-purpose aspect-oriented extension to Java. A series of abridged
      examples illustrate the kinds of aspects programmers may want to
      implement using AspectJ and the benefits associated with doing so.
      Readers who would like to understand the examples in more detail, or who
      want to learn how to program examples like these, can find the complete
      examples and supporting material on the AspectJ web site(<ulink
      url="http://aspectj.org/documentation/papersAndSlides/figures-cacm2001.zip"></ulink>).</para>

    <para>A significant risk in adopting any new technology is going too
      far too fast. Concern about this risk causes many organizations to
      be conservative about adopting new technology. To address this
      issue, the examples in this chapter are grouped into three broad
      categories, with aspects that are easier to adopt into existing
      development projects coming earlier in this chapter. The next
      section, <xref linkend="aspectjsemantics"/>, we present the core
      of AspectJ's semantics, and in <xref linkend="developmentaspects"/>,
      we present aspects that facilitate tasks such as debugging,
      testing and performance tuning of applications. And, in the section
      following, <xref linkend="productionaspects"/>, we present aspects
      that implement crosscutting functionality common in Java
      applications. We will defer discussing a third category of aspects,
      reusable aspects until <xref linkend="aspectjlanguage"/>. </para>

    <para>These categories are informal, and this ordering is not the only way
      to adopt AspectJ. Some developers may want to use a production aspect
      right away. But our experience with current AspectJ users suggests that
      this is one ordering that allows developers to get experience with (and
      benefit from) AOP technology quickly, while also minimizing risk.</para>

  </sect1>

  <sect1 id="aspectjsemantics" xreflabel="AspectJ Semantics">
    <title>AspectJ Semantics</title>

    <indexterm>
      <primary>AspectJ</primary>
      <secondary>semantics</secondary>
      <tertiary>overview</tertiary>
    </indexterm>

    <para>This section presents a brief introduction to the features of AspectJ
      used later in this chapter. These features are at the core of the
      language, but this is by no means a complete overview of AspectJ.</para>

    <para>The semantics are presented using a simple figure editor system. A
      <classname>Figure</classname> consists of a number of
      <classname>FigureElements</classname>, which can be either
      <classname>Point</classname>s or <classname>Line</classname>s. The
      <classname>Figure</classname> class provides factory services. There is
      also a <classname>Display</classname>. Most example programs later in
      this chapter are based on this system as well.</para>

    <para>
      <mediaobject>
        <imageobject>
          <imagedata fileref="figureUML.gif"/>
        </imageobject>
        <caption><para>UML for the <literal>FigureEditor</literal>
            example</para></caption>
      </mediaobject>
    </para>

    <para>The motivation for AspectJ (and likewise for aspect-oriented
      programming) is the realization that there are issues or concerns
      that are not well captured by traditional programming
      methodologies. Consider the problem of enforcing a security policy
      in some application. By its nature, security cuts across many of
      the natural units of modularity of the application. Moreover, the
      security policy must be uniformly applied to any additions as the
      application evolves. And the security policy that is being applied
      might itself evolve. Capturing concerns like a security policy in
      a disciplined way is difficult and error-prone in a traditional
      programming language.</para>

    <para>Concerns like security cut across the natural units of
      modularity. For object-oriented programming languages, the natural
      unit of modularity is the class. But in object-oriented
      programming languages, crosscutting concerns are not easily turned
      into classes precisely because they cut across classes, and so
      these aren't reusable, they can't be refined or inherited,
      they are spread through out the program in an undisciplined way,
      in short, they are difficult to work with.</para>

    <para>Aspect-oriented programming is a way of modularizing
      crosscutting concerns much like object-oriented programming is a
      way of modularizing common concerns. AspectJ is an implementation
      of aspect-oriented programming for Java.</para>

    <para>AspectJ adds to Java just one new concept, a join point, and
      a few new constructs: pointcuts, advice, introduction and aspects.
      Pointcuts and advice dynamically affect program flow, and
      introduction statically affects a program's class
      heirarchy.</para>

    <para>A <emphasis>join point</emphasis>
      <indexterm><primary>join point</primary></indexterm>
      is a well-defined point in the program flow.
      <emphasis>Pointcuts</emphasis>
      <indexterm><primary>pointcut</primary></indexterm>
      select certain join points and values at those points.
      <emphasis>Advice</emphasis>
      <indexterm> <primary>advice</primary></indexterm>
      defines code that is executed when a pointcut is reached. These
      are, then, the dynamic parts of AspectJ.</para>

    <para>AspectJ also has a way of affecting a program statically.
      <emphasis>Introduction</emphasis>
      <indexterm><primary>introduction</primary></indexterm>
      is how AspectJ modifies a program's static structure, namely, the
      members of its classes and the relationship between
      classes.</para>

    <para>The last new construct in AspectJ is the
      <emphasis>aspect</emphasis>.
      <indexterm><primary>aspect</primary></indexterm>
      Aspects, are AspectJ's unit of modularity for crosscutting
      concerns They are defined in terms of pointcuts, advice and
      introduction.</para>

    <para>In the sections immediately following, we are first going to look at
      join points and how they compose into pointcuts. Then we will look
      at advice, the code which is run when a pointcut is reached. We
      will see how to combine pointcuts and advice into aspects, AspectJ's
      reusable, inheritable unit of modularity. Lastly, we will look at
      how to modify a program's class structure with introduction. </para>

    <sect2>
      <title>The Dynamic Join Point Model</title>
      <indexterm>
        <primary>join point</primary>
        <secondary>model</secondary>
      </indexterm>

      <para>A critical element in the design of any aspect-oriented
        language is the join point model. The join point model provides
        the common frame of reference that makes it possible to define
        the dynamic structure of crosscutting concerns.</para>

      <para>This chapter describes AspectJ's dynamic join points, in
        which join points are certain well-defined points in the
        execution of the program. Later we will discuss introduction,
        AspectJ's form for modifying a program statically. </para>

      <para>AspectJ provides for many kinds of join points, but this
        chapter discusses only one of them: method call join points. A
        method call join point encompasses the actions of an object
        receiving a method call. It includes all the actions that
        comprise a method call, starting after all arguments are
        evaluated up to and including normal or abrupt return.</para>

      <para>Each method call itself is one join point. The dynamic
        context of a method call may include many other join points: all
        the join points that occur when executing the called method and
        any methods that it calls.</para>

    </sect2>

    <sect2>
      <title>Pointcut Designators</title>

      <para>In AspectJ, <emphasis>pointcut designators</emphasis> (or
      simply pointcuts) identify certain join points in the program
      flow. For example, the pointcut</para>

      <programlisting format="linespecific">
call(void Point.setX(int))</programlisting>

      <para>identifies any call to the method <function>setX</function>
        defined on <classname>Point</classname> objects. Pointcuts can be
        composed using a filter composition semantics, so for example:</para>

     <programlisting format="linespecific">
call(void Point.setX(int)) ||
call(void Point.setY(int))</programlisting>

      <para>identifies any call to either the <function>setX</function> or
        <function>setY</function> methods defined by
        <classname>Point</classname>.</para>

      <para>Programmers can define their own pointcuts, and pointcuts
        can identify join points from many different classes &mdash; in
        other words, they can crosscut classes. So, for example, the
        following declares a new, named pointcut:</para>

<programlisting format="linespecific">
pointcut move(): call(void FigureElement.setXY(int,int)) ||
                 call(void Point.setX(int))              ||
                 call(void Point.setY(int))              ||
                 call(void Line.setP1(Point))            ||
                 call(void Line.setP2(Point));</programlisting>

      <para>The effect of this declaration is that <function>move</function> is
      now a pointcut that identifies any call to methods that move figure
      elements. </para>

      <sect3>
        <title>Property-Based Primitive Pointcuts</title>
        <indexterm>
          <primary>pointcut</primary>
          <secondary>primitive</secondary>
          </indexterm>
        <indexterm>
          <primary>pointcut</primary>
          <secondary>name-based</secondary>
        </indexterm>
        <indexterm>
          <primary>pointcut</primary>
          <secondary>property-based</secondary>
        </indexterm>

      <para>The previous pointcuts are all based on explicit enumeration
          of a set of method signatures. We call this
          <emphasis>name-based</emphasis> crosscutting. AspectJ also
          provides mechanisms that enable specifying a pointcut in terms
          of properties of methods other than their exact name. We call
          this <emphasis>property-based</emphasis> crosscutting. The
          simplest of these involve using wildcards in certain fields of
          the method signature. For example:</para>

<programlisting format="linespecific">
call(void Figure.make*(..))</programlisting>

        <para>identifies calls to any method defined on
          <classname>Figure</classname>, for which the name begins with
          "<function>make</function>", specifically the factory methods
          <function>makePoint</function> and <function>makeLine</function>;
          and</para>

      <programlisting format="linespecific">
call(public * Figure.* (..))</programlisting>

        <para>identifies calls to any public method defined on
          <classname>Figure</classname>.</para>

        <para>One very powerful primitive pointcut,
          <function>cflow</function>, identifies join points based on whether
          they occur in the dynamic context of another pointcut. So</para>

        <programlisting format="linespecific">
cflow(move())</programlisting>

       <para>identifies all join points that occur between receiving method
          calls for the methods in <function>move</function> and returning from
          those calls (either normally or by throwing an exception.) </para>

      </sect3>

    </sect2>

    <sect2>
      <title>Advice</title>
      <indexterm>
        <primary>advice</primary>
      </indexterm>

      <para>Pointcuts are used in the definition of advice. AspectJ has
        several different kinds of advice that define additional code that
        should run at join points. <emphasis>Before advice</emphasis>
        <indexterm>
          <primary>advice</primary>
          <secondary>before</secondary>
        </indexterm>
        runs when a join point is reached and
        before the computation proceeds, i.e. it runs when computation
        reaches the method call and before the actual method starts running.
        <emphasis>After advice</emphasis>
        <indexterm>
          <primary>advice</primary>
          <secondary>after</secondary>
        </indexterm>
        runs after the computation 'under the join point' finishes, i.e. after
        the method body has run, and just before control is returned to the
        caller. <emphasis>Around advice</emphasis>
        <indexterm>
          <primary>advice</primary>
          <secondary>around</secondary>
        </indexterm>
        runs when the join point is reached, and has explicit control over
        whether the computation under the join point is allowed to run at
        all. (Around advice and some variants of after advice are not
        discussed in this chapter.)</para>

<programlisting><![CDATA[
after(): move() {
    System.out.println("A figure element moved.");
}
]]></programlisting>

      <sect3>
        <title>Exposing Context in Pointcuts</title>

      <para>Pointcuts can also expose part of the execution context at
          their join points. Values exposed by a pointcut can be used in
          the body of advice declarations. In the following code, the
          pointcut exposes three values from calls to
          <function>setXY</function>: the
          <classname>FigureElement</classname> receiving the call, the
          new value for <literal>x</literal> and the new value for
          <literal>y</literal>. The advice then prints the figure
          element that was moved and its new <literal>x</literal> and
          <literal>y</literal> coordinates after each
          <classname>setXY</classname> method call.</para>

<programlisting><![CDATA[
pointcut setXY(FigureElement fe, int x, int y):
   call(void FigureElement.setXY(int, int)) 
   && target(fe) 
   && args(x, y);

after(FigureElement fe, int x, int y): setXY(fe, x, y) {
   System.out.println(fe + " moved to (" + x + ", " + y + ").");
}
]]></programlisting>

      </sect3>

    </sect2>

    <sect2>
      <title>Introduction</title>
      <indexterm><primary>aspect</primary></indexterm>

      <para>Introduction is AspectJ's form for modifying classes and their
        hierarchy. Introduction adds new members to classes and alters the
        inheritance relationship between classes. Unlike advice that operates
        primarily dynamically, introduction operates statically, at compilation
        time. Introduction changes the declaration of classes, and it is these
        changed classes that are inherited, extended or instantiated by the
        rest of the program.</para>

      <para>Consider the problem of adding a new capability to some existing
        classes that are already part of a class heirarchy, i.e. they already
        extend a class. In Java, one creates an interface that captures
        this new capability, and then adds to <emphasis>each affected
          class</emphasis> a method that implements this interface.</para>

      <para>AspectJ can do better. The new capability is a crosscutting concern
        because it affects multiple classes. Using AspectJ's introduction form,
        we can introduce into existing classes the methods or fields that are
        necessary to implement the new capability.
        </para>

      <para>Suppose we want to have <classname>Screen</classname> objects
        observe changes to <classname>Point</classname> objects, where
        <classname>Point</classname> is an existing class. We can implement
        this by introducing into the class <classname>Point</classname> an
        instance field, <varname>observers</varname>, that keeps track of the
        <classname>Screen</classname> objects that are observing
        <classname>Point</classname>s. Observers are added or removed with the
        static methods <function>addObserver</function> and
        <function>removeObserver</function>. The pointcut
        <function>changes</function> defines what we want to observe, and the
        after advice defines what we want to do when we observe a change. Note
        that neither <classname>Screen</classname>'s nor
        <classname>Point</classname>'s code has to be modified, and that all
        the changes needed to support this new capability are local to this
        aspect.</para>

      <programlisting><![CDATA[
aspect PointObserving {

   private Vector Point.observers = new Vector();

   public static void addObserver(Point p, Screen s) {
      p.observers.add(s);
   }

   public static void removeObserver(Point p, Screen s) {
      p.observers.remove(s);
   }

   pointcut changes(Point p): target(p) && call(void Point.set*(int));

   after(Point p): changes(p) {
      Iterator iter = p.observers.iterator();
      while ( iter.hasNext() ) {
         updateObserver(p, (Screen)iter.next());
      }
   }

   static void updateObserver(Point p, Screen s) {
      s.display(p);
   }
}]]></programlisting>
    </sect2>

    <sect2>
      <title>Aspect Declarations</title>

      <para>An <emphasis>aspect</emphasis>
          <indexterm><primary>aspect</primary></indexterm> is a modular unit of
          crosscutting implementation. It is defined very much like a class,
          and can have methods, fields, and initializers. The crosscutting
          implementation is provided in terms of pointcuts, advice and
          introductions.  Only aspects may include advice, so while AspectJ
          may define crosscutting effects, the declaration of those effects is
          localized.</para>

      <para>The next three sections present the use of aspects in
        increasingly sophisticated ways. Development aspects are easily removed
        from production builds. Production aspects are intended to be used in
        both development and in production, but tend to affect only a few
        classes. Finally, reusable aspects require the most experience to get
        right.</para>

    </sect2>

  </sect1>

  <sect1 id="developmentaspects" xreflabel="Development Aspects">
    <title>Development Aspects</title>
    <indexterm>
      <primary>aspect</primary>
      <secondary>development</secondary>
    </indexterm>

    <para>This section presents examples of aspects that can be used during
      development of Java applications. These aspects facilitate debugging,
      testing and performance tuning work. The aspects define behavior that
      ranges from simple tracing, to profiling, to testing of internal
      consistency within the application. Using AspectJ makes it possible to
      cleanly modularize this kind of functionality, thereby making it possible
      to easily enable and disable the functionality when desired. </para>

    <sect2>
      <title>Tracing, Logging, and Profiling</title>
      <indexterm>
        <primary>tracing</primary>
      </indexterm>
      <indexterm>
        <primary>logging</primary>
      </indexterm>
      <indexterm>
        <primary>profiling</primary>
      </indexterm>

      <para>This first example shows how to increase the visibility of the
        internal workings of a program. It is a simple tracing aspect that
        prints a message at specified method calls. In our figure editor
        example, one such aspect might simply trace whenever points are
        drawn.</para>

<programlisting><![CDATA[
aspect SimpleTracing {
  pointcut tracedCall():
    call(void FigureElement.draw(GraphicsContext));

  before(): tracedCall() {
    System.out.println("Entering: " + thisJoinPoint);
  }
}
]]></programlisting>

      <para>This code makes use of the <literal>thisJoinPoint</literal> special
        variable. Within all advice bodies this variable is bound to an object
        that describes the current join point. The effect of this code
        is to print a line like the following every time a figure element
        receives a <function>draw</function> method call:</para>

<programlisting><![CDATA[
Entering: call(void FigureElement.draw(GraphicsContext))
]]></programlisting>

      <para>To understand the benefit of coding this with AspectJ consider
        changing the set of method calls that are traced. With AspectJ, this
        just requires editing the definition of the
        <function>tracedCalls</function> pointcut and recompiling. The
        individual methods that are traced do not need to be edited.</para>

      <para>When debugging, programmers often invest considerable effort in
        figuring out a good set of trace points to use when looking for a
        particular kind of problem. When debugging is complete   or appears to
        be complete   it is frustrating to have to lose that investment by
        deleting trace statements from the code. The alternative of just
        commenting them out makes the code look bad, and can cause trace
        statements for one kind of debugging to get confused with trace
        statements for another kind of debugging.</para>

      <para>With AspectJ it is easy to both preserve the work of designing a
        good set of trace points and disable the tracing when it isn t being
        used. This is done by writing an aspect specifically for that tracing
        mode, and removing that aspect from the compilation when it is not
        needed.</para>

      <para>This ability to concisely implement and reuse debugging
        configurations that have proven useful in the past is a direct result
        of AspectJ modularizing a crosscutting design element the set of
        methods that are appropriate to trace when looking for a given kind of
        information.</para>

      <sect3>
        <title>Profiling and Logging</title>
        <indexterm><primary>logging</primary></indexterm>
        <indexterm><primary>profiling</primary></indexterm>

        <para> Our second example shows you how to do some very specific
          profiling. Although many sophisticated profiling tools are available,
          and these can gather a variety of information and display the results
          in useful ways, you may sometimes want to profile or log some very
          specific behavior. In these cases, it is often possible to write a
          simple aspect similar to the ones above to do the job.</para>

        <para>For example, the following aspect<footnote>
            <para>Since aspects are by default singleton aspects, i.e. there is
              only one instance of the aspect, fields in a singleton aspect are
              similar to static fields in class.</para></footnote> will count
          the number of calls to the <function>rotate</function> method on a
          <classname>Line</classname> and the number of calls to the
          <function>set*</function> methods of a <classname>Point</classname>
          that happen within the control flow of those calls to
          <function>rotate</function>:</para>

<programlisting><![CDATA[
aspect SetsInRotateCounting {
  int rotateCount = 0;
  int setCount = 0;

  before(): call(void Line.rotate(double)) {
    rotateCount++;
  }

  before(): call(void Point.set*(int)) &&
            cflow(call(void Line.rotate(double))) {
    setCount++;
  }
}]]></programlisting>

        <para>Aspects have an advantage over standard profiling or logging
          tools because they can be programmed to ask very specific and complex
          questions like, "How many times is the <function>rotate</function>
          method defined on <classname>Line</classname> objects called, and how
          many times are methods defined on <classname>Point</classname>
          objects whose name begins with `<function>set</function>' called in
          fulfilling those rotate calls"?</para>

      </sect3>

    </sect2>

    <sect2>
      <title>Pre- and Post-Conditions</title>

      <indexterm><primary>pre-condition</primary></indexterm>
      <indexterm><primary>post-condition</primary></indexterm>
      <indexterm><primary>assertion</primary></indexterm>

      <para>Many programmers use the "Design by Contract" style popularized by
        Bertand Meyer in <citetitle>Object-Oriented Software Construction,
          2/e</citetitle>. In this style of programming, explicit
        pre-conditions test that callers of a method call it properly and
        explicit post-conditions test that methods properly do the work they
        are supposed to.</para>

      <para>
        AspectJ makes it possible to implement pre- and post-condition testing
        in modular form. For example, this code </para>


      <programlisting><![CDATA[
aspect PointBoundsChecking {

  pointcut setX(int x): 
      (call(void FigureElement.setXY(int, int)) && args(x, *)) 
      || (call(void Point.setX(int)) && args(x));

  pointcut setY(int y): 
      (call(void FigureElement.setXY(int, int)) && args(*, y)) 
      || (call(void Point.setY(int)) && args(y));

  before(int x): setX(x) {
    if ( x < MIN_X || x > MAX_X )
      throw new IllegalArgumentException("x is out of bounds.");
  }

  before(int y): setY(y) {
    if ( y < MIN_Y || y > MAX_Y )
      throw new IllegalArgumentException("y is out of bounds.");
  }
}
]]></programlisting>

      <para>implements the bounds checking aspect of pre-condition testing for
        operations that move points. Notice that the <function>setX</function>
        pointcut refers to all the operations that can set a point's
        <literal>x</literal> coordinate; this includes the
        <function>setX</function> method, as well as half of  the
        <function>setXY</function> method. In this sense the
        <function>setX</function> pointcut can be seen as involving very
        fine-grained crosscutting&mdash;it names the the
        <function>setX</function> method and half of the
        <function>setXY</function> method.</para>

      <para>Even though pre- and post-condition testing aspects can often be
        used only during testing, in some cases developers may wish to include
        them in the production build as well. Again, because AspectJ makes it
        possible to modularize these crosscutting concerns cleanly, it gives
        developers good control over this decision.</para>

    </sect2>

    <sect2>
      <title>Contract Enforcement</title>
      <indexterm><primary>contract enforcement</primary></indexterm>

<!--  <remark>What is a compelling example of runtime contract enforcement that has -->
<!--    croscutting concerns so that Java 1.4-based assertions won't be -->
<!--    sufficient? -->
<!--  </remark> -->
      <para>
        The property-based crosscutting mechanisms can be very useful in
        defining more sophisticated contract enforcement. One very powerful
        use of these mechanisms is to identify method calls that, in a correct
        program, should not exist. For example, the following aspect enforces
        the constraint that only the well-known factory methods can add an
        element to the registry of figure elements. Enforcing this constraint
        ensures that no figure element is added to the registry more than
        once.</para>

<programlisting><![CDATA[
static aspect RegistrationProtection {

  pointcut register(): call(void Registry.register(FigureElement));

  pointcut canRegister(): withincode(static * FigureElement.make*(..));

  before(): register() && !canRegister() {
    throw new IllegalAccessException("Illegal call " + thisJoinPoint);
  }
}
]]></programlisting>

      <para>This aspect uses the withincode primitive pointcut to denote all
        join points that occur within the body of the factory methods on
        <classname>FigureElement</classname> (the methods with names that begin
        with "<literal>make</literal>"). This is a property-based pointcut
        because it identifies join points based not on their signature, but
        rather on the property that they occur specifically within the code of
        another method. The before advice declaration effectively says  signal
        an error for any calls to register that are not within the factory
        methods.</para>

    </sect2>

    <sect2 id="configurationmanagement" xreflabel="Configuration Management">
      <title>Configuration Management</title>
      <indexterm>
        <primary>configuration management</primary>
      </indexterm>

      <para>Configuration management for aspects can be handled using a variety
        of make-file like  techniques. To work with optional aspects, the
        programmer can simply define their make files to either include the
        aspect in the call to the AspectJ compiler or not, as desired.</para>

      <para>Developers who want to be certain that no aspects are included in
        the production build can do so by configuring their make files so that
        they use a traditional Java compiler for production builds. To make it
        easy to write such make files, the AspectJ compiler has a command-line
        interface that is consistent with ordinary Java compilers.</para>
    </sect2>

  </sect1>

  <sect1 id="productionaspects" xreflabel="Production Aspects">
    <title>Production Aspects</title>
    <indexterm>
      <primary>aspect</primary>
      <secondary>production</secondary>
    </indexterm>

      <para>This section presents examples of aspects that are inherently
      intended to be included in the production builds of an application.
      Production aspects tend to add functionality to an application rather
      than merely adding more visibility of the internals of a program. Again,
      we begin with name-based aspects and follow with property-based aspects.
      Name-based production aspects tend to affect only a small number of
      methods. For this reason, they are a good next step for projects
      adopting AspectJ. But even though they tend to be small and simple, they
      can often have a significant effect in terms of making the program easier
      to understand and maintain.</para>

    <sect2>
      <title>Change Monitoring</title>
      <indexterm><primary>change monitoring</primary></indexterm>

      <para>The first example production aspect shows how one might implement
        some simple functionality where it is problematic to try and do it
        explicitly. It supports the code that refreshes the display. The role
        of the aspect is to maintain a dirty bit indicating whether or not an
        object has moved since the last time the display was refreshed.</para>

      <para>Implementing this functionality as an aspect is straightforward.
        The <function>testAndClear</function> method is called by the display
        code to find out whether a figure element has moved recently. This
        method returns the current state of the dirty flag and resets it to
        false. The pointcut <function>move</function> captures all the method
        calls that can move a figure element. The after advice on
        <function>move</function> sets the dirty flag whenever an object
        moves.</para>

<programlisting><![CDATA[
aspect MoveTracking {

  private static boolean dirty = false;

  public static boolean testAndClear() {
    boolean result = dirty;
    dirty = false;
    return result;
  }

  pointcut move(): call(void FigureElement.setXY(int, int)) ||
                   call(void Line.setP1(Point))             ||
                   call(void Line.setP2(Point))             ||
                   call(void Point.setX(int))               ||
                   call(void Point.setY(int));

  after() returning: move() {
    dirty = true;
  }
}
]]></programlisting>

      <para>Even this simple example serves to illustrate some of the important
        benefits of using AspectJ in production code. Consider implementing
        this functionality with ordinary Java: there would likely be a helper
        class that contained the <literal>dirty</literal> flag, the
        <function>testAndClear</function> method, as well as a
        <function>setFlag</function> method. Each of the methods that could
        move a figure element would include a call to the
        <function>setFlag</function> method. Those calls, or rather the concept
        that those calls should happen at each move operation, are the
        crosscutting concern in this case. </para>

      <para>The AspectJ implementation has several advantages over the standard
        implementation:</para>

      <para><emphasis>The structure of the crosscutting concern is captured
          explicitly.</emphasis> The moves pointcut clearly states all the
        methods involved, so the programmer reading the code sees not just
        individual calls to <literal>setFlag</literal>, but instead sees the
        real structure of the code. The IDE support included with AspectJ
        automatically reminds the programmer that this aspect advises each of
        the methods involved.  The IDE support also provides commands to jump
        to the advice from the method and vice-versa.</para>

      <para><emphasis>Evolution is easier.</emphasis> If, for example, the
        aspect needs to be revised to record not just that some figure element
        moved, but rather to record exactly which figure elements moved, the
        change would be entirely local to the aspect. The pointcut would be
        updated to expose the object being moved, and the advice would be
        updated to record that object. The paper <citetitle>An Overview of
          AspectJ</citetitle>, presented at ECOOP 2001, presents a detailed
        discussion of various ways this aspect could be expected to
        evolve.)</para>

      <para><emphasis>The functionality is easy to plug in and out.</emphasis>
        Just as with development aspects, production aspects may need to be
        removed from the system, either because the functionality is no longer
        needed at all, or because it is not needed in certain configurations of
        a system. Because the functionality is modularized in a single aspect
        this is easy to do.</para>

      <para><emphasis>The implementation is more stable.</emphasis> If, for
        example, the programmer adds a subclass of <classname>Line</classname>
        that overrides the existing methods, this advice in this aspect will
        still apply. In the ordinary Java implementation the programmer would
        have to remember to add the call to <function>setFlag</function> in the
        new overriding method. This benefit is often even more compelling for
        property-based aspects (see the section <xref
        linkend="consistentbehavior"/>). </para>
    </sect2>

    <sect2>
      <title>Context Passing</title>

      <para>The crosscutting structure of context passing can be a significant
        source of complexity in Java programs. Consider implementing
        functionality that would allow a client of the figure editor (a program
        client rather than a human) to set the color of any figure elements
        that are created. Typically this requires passing a color, or a color
        factory, from the client, down through the calls that lead to the
        figure element factory. All programmers are familiar with the
        inconvenience of adding a first argument to a number of methods just to
        pass this kind of context information.</para>

      <para>Using AspectJ, this kind of context passing can be implemented in a
        modular way. The following code adds after advice that runs only when
        the factory methods of <classname>Figure</classname> are called in the
        control flow of a method on a
        <classname>ColorControllingClient</classname>. </para>

<programlisting><![CDATA[
aspect ColorControl {

  pointcut CCClientCflow(ColorControllingClient client):
    cflow(call(* * (..)) && target(client));

  pointcut make(): call(FigureElement Figure.make*(..));

  after (ColorControllingClient c) returning (FigureElement fe):
        make() && CCClientCflow(c) {

    fe.setColor(c.colorFor(fe));
  }
}]]></programlisting>

      <para>This aspect affects only a small number of methods, but note that
        the non-AOP implementation of this functionality might require editing
        many more methods, specifically, all the methods in the control flow
        from the client to the factory. This is a benefit common to many
        property-based aspects   while the aspect is short and affects only a
        modest number of benefits, the complexity the aspect saves is
        potentially much larger.</para>

      </sect2>

    <sect2 id="consistentbehavior" xreflabel="Providing Consistent Behavior">
      <title>Providing Consistent Behavior</title>

      <para>This example shows how a property-based aspect can be used to
        provide consistent handling of functionality across a large set of
        operations. This aspect ensures that all public methods of the
        <literal>com.xerox</literal> package log any errors (a kind of
        throwable, different from Exception) they throw to their caller. The
        <function>publicMethodCall</function> pointcut captures the public
        method calls of the package, and the after advice runs whenever one of
        those calls returns throwing an exception. The advice logs the
        exception and then the throw resumes.</para>

      <programlisting><![CDATA[
aspect PublicErrorLogging {
   Log log = new Log();

   pointcut publicMethodCall(): call(public * com.xerox.*.*(..));

   after() throwing (Error e): publicMethodCall() { log.write(e); }
}]]></programlisting>

      <para>In some cases this aspect can log an exception twice. This happens
        if code inside the <literal>com.xerox</literal> package itself calls a
        public method of the package. In that case this code will log the error
        at both the outermost call into the <literal>com.xerox</literal>
        package and the re-entrant call. The <function>cflow</function>
        primitive pointcut can be used in a nice way to exclude these
        re-entrant calls:</para>

      <programlisting><![CDATA[
after() throwing (Error e): publicMethodCall() &&
                            !cflow(publicMethodCall()) {
   log.write(e);
}]]></programlisting>


      <para>The following aspect is taken from work on the AspectJ compiler.
        The aspect advises about 35 methods in the
        <classname>JavaParser</classname> class. The individual methods handle
        each of the different kinds of elements that must be parsed. They have
        names like <function>parseMethodDec</function>,
        <function>parseThrows</function>, and
        <function>parseExpr</function>.</para>

      <programlisting><![CDATA[
aspect ContextFilling {
   pointcut parse(JavaParser jp):
         call(* JavaParser.parse*(..))
         && target(jp)
         && !call(Stmt parseVarDec(boolean)); // var decs
                                              // are tricky

   around(JavaParser jp) returns ASTObject: parse(jp) {
      Token beginToken = jp.peekToken();
      ASTObject ret = proceed(jp);
      if (ret != null) jp.addContext(ret, beginToken);
      return ret;
   }
}]]></programlisting>

      <para>This example exhibits a property found in many aspects with large
        property-based pointcuts. In addition to a general property based
        pattern <literal>call(* JavaParser.parse*(..))</literal> it includes an
        exception to the pattern <literal>!call(Stmt
        parseVarDec(boolean))</literal>. The exclusion of
        <function>parseVarDec</function> happens because the parsing of
        variable declarations in Java is too complex to fit with the clean
        pattern of the other <function>parse*</function> methods. Even with the
        explicit exclusion this aspect is a clear expression of a clean
        crosscutting modularity. Namely that all <function>parse*</function>
        methods that return <classname>ASTObjects</classname>, except for
        <function>parseVarDec</function> share a common behavior for
        establishing the parse context of their result. </para>

      <para>The process of writing an aspect with a large property-based
        pointcut, and of developing the appropriate exceptions can clarify the
        structure of the system. This is especially true, as in this case, when
        refactoring existing code to use aspects. When we first looked at the
        code for this aspect, we were able to use the IDE support provided in
        AJDE for JBuilder to see what methods the aspect was advising compared
        to our manual coding. We quickly discovered that there were a dozen
        places where the aspect advice was in effect but we had not manually
        inserted the required functionality. Two of these were bugs in our
        prior non-AOP implementation of the parser. The other ten were needless
        performance optimizations. So, here, refactoring the code to express
        the crosscutting structure of the aspect explicitly made the code more
        concise and eliminated latent bugs.</para>

    </sect2>

  </sect1>

  <sect1>
    <title>Static Crosscutting: Introduction</title>
      <indexterm><primary>introduction</primary></indexterm>

 <para>Up until now we have only seen constructs that allow us to
        implement dynamic crosscutting, crosscutting that changes the way a
        program executes. AspectJ also allows us to implement static
        crosscutting, crosscutting that affects the static structure of our
        progams. This is done using forms called introduction.</para>

      <para>An <emphasis>introduction</emphasis> is a member of an aspect, but
      it defines or modifies a member of another type (class). With
      introduction we can</para>
        <itemizedlist>
          <listitem>
            <para>add methods to an existing class</para>
          </listitem>
          <listitem>
            <para>add fields to an existing class</para>
          </listitem>
          <listitem>
            <para>extend an existing class with another</para>
          </listitem>
          <listitem>
            <para>implement an interface in an existing class</para>
          </listitem>
          <listitem>
            <para>convert checked exceptions into unchecked exceptions</para>
          </listitem>
        </itemizedlist>

      <para>Suppose we want to change the class
      <classname>Point</classname> to support cloning. By using introduction,
      we can add that capability. The class itself doesn't change, but its
      users (here the method <function>main</function>) may. In the example
      below, the aspect <classname>CloneablePoint</classname> does three
      things: </para>
        <orderedlist>
          <listitem>
            <para>declares that the class
              <classname>Point</classname> implements the interface
              <classname>Cloneable</classname>,</para>
          </listitem>
          <listitem>
          <para>declares that the methods in <classname>Point</classname> whose
            signature matches <literal>Object clone()</literal> should have
            their checked exceptions converted into unchecked exceptions,
            and</para>
          </listitem>
          <listitem>
            <para>adds a method that overrides the method
            <function>clone</function> in <classname>Point</classname>, which
            was inherited from <classname>Object</classname>.</para>
          </listitem>
        </orderedlist>

      <programlisting>
class Point {
   private int x, y;

   Point(int x, int y) { this.x = x; this.y = y; }

   int getX() { return this.x; }
   int getY() { return this.y; }

   void setX(int x) { this.x = x; }
   void setY(int y) { this.y = y; }

   public static void main(String[] args) {

      Point p = new Point(3,4);
      Point q = (Point) p.clone();
   }
}

aspect CloneablePoint {
   declare parents: Point implements Cloneable;

   declare soft: CloneNotSupportedException: execution(Object clone());

   Object Point.clone() { return super.clone(); }
}</programlisting>

      <para>Introduction is a powerful mechanism for capturing crosscutting
        concerns because it not only changes the behavior of components in an
        application, but also changes their relationship.</para>

  </sect1>

  <sect1>
    <title>Conclusion</title>

    <para>AspectJ is a simple and practical aspect-oriented extension to
      Java. With just a few new constructs, AspectJ provides support for modular
      implementation of a range of crosscutting concerns.</para>

    <para> Adoption of AspectJ into an existing Java development project can be
      a straightforward and incremental task. One path is to begin by
      using only development aspects, going on to using production aspects and
      then reusable aspects after building up experience with AspectJ. Adoption
      can follow other paths as well. For example, some developers will
      benefit from using production aspects right away. Others may be able to
      write clean reusable aspects almost right away.</para>

    <para>AspectJ enables both name-based and property based crosscutting.
      Aspects that use name-based crosscutting tend to affect a small number of
      other classes. But despite their small scale, they can often eliminate
      significant complexity compared to an ordinary Java implementation.
      Aspects that use property-based crosscutting can have small or large
      scale.</para>

    <para>Using AspectJ results in clean well-modularized implementations of
      crosscutting concerns. When written as an AspectJ aspect the structure
      of a crosscutting concern is explicit and easy to understand. Aspects
      are also highly modular, making it possible to develop plug-and-play
      implementations of crosscutting functionality.</para>

    <para>AspectJ provides more functionality than was covered by this short
      introduction. The next chapter, <xref linkend="aspectjlanguage"/>, covers
      in detail all the features of the AspectJ language. The following
      chapter, <xref linkend="examples"/>, then presents some carefully chosen
      examples that show you how AspectJ might be used. We recommend that you
      read the next two chapters carefully before deciding to adopt AspectJ
      into a project.
    </para>

  </sect1>

</chapter>

<!--
Local variables:
compile-command: "build.sh"
fill-column: 79
sgml-local-ecat-files: progguide.ced
sgml-parent-document:("progguide.xml" "book" "chapter")
End:
-->