/usr/share/doc/aspectj-doc/progguide/examples-basic.html

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Basic Techniques</title><link rel="stylesheet" type="text/css" href="aspectj-docs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="The AspectJTM Programming Guide"><link rel="up" href="examples.html" title="Chapter 3. Examples"><link rel="prev" href="examples-howto.html" title="Obtaining, Compiling and Running the Examples"><link rel="next" href="examples-development.html" title="Development Aspects"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Basic Techniques</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="examples-howto.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Examples</th><td width="20%" align="right"> <a accesskey="n" href="examples-development.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="examples-basic"></a>Basic Techniques</h2></div></div></div><p>
      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.
    </p><p>
      The first example, <a class="xref" href="examples-basic.html#examples-joinPoints" title="Join Points and thisJoinPoint">the section called &#8220;Join Points and <code class="literal">thisJoinPoint</code>&#8221;</a>, is about
      gathering and using information about the join point that has
      triggered some advice. The second example, <a class="xref" href="examples-basic.html#examples-roles" title="Roles and Views">the section called &#8220;Roles and Views&#8221;</a>, concerns a crosscutting view of an
      existing class hierarchy. </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="examples-joinPoints"></a>Join Points and <code class="literal">thisJoinPoint</code></h3></div></div></div><p>
        (The code for this example is in
        <code class="filename"><em class="replaceable"><code>InstallDir</code></em>/examples/tjp</code>.)
      </p><p>
        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 program reaches a join
        point, advice on that join point may run in addition to (or instead
        of) the join point itself.
      </p><p>
        When using a pointcut that picks out join points of a single kind
        by name, typicaly the the advice will know exactly what kind of
        join point it is associated with.  The pointcut may even publish
        context about the join point.  Here, for example, since the only
        join points picked out by the pointcut are calls of a certain
        method, we can get the target value and one of the argument values
        of the method calls directly.
      </p><pre class="programlisting">
before(Point p, int x): target(p)
                     &amp;&amp; args(x)
                     &amp;&amp; call(void setX(int)) {
    if (!p.assertX(x)) {
        System.out.println("Illegal value for x"); return;
    }
}
</pre><p>
       But sometimes the shape of the join point is not so clear.  For
       instance, suppose a complex application is being debugged, and we
       want to trace when any method of some class is executed.  The
       pointcut
     </p><pre class="programlisting">
pointcut execsInProblemClass(): within(ProblemClass)
                             &amp;&amp; execution(* *(..));
</pre><p>
        will pick out each execution join point of every method defined
        within <code class="classname">ProblemClass</code>.  Since advice executes
        at each join point picked out by the pointcut, we can reasonably
        ask which join point was reached.
      </p><p>
        Information about the join point that was matched is available to
        advice through the special variable
        <code class="varname">thisJoinPoint</code>, of type <a class="ulink" href="../api/org/aspectj/lang/JoinPoint.html" target="_top"><code class="classname">org.aspectj.lang.JoinPoint</code></a>.
        Through this object we can access information such as</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem">
          the kind of join point that was matched
        </li><li class="listitem">
          the source location of the code associated with the join point
        </li><li class="listitem">
          normal, short and long string representations of the
          current join point
        </li><li class="listitem">
          the actual argument values of the join point
        </li><li class="listitem">
          the signature of the member associated with the join point
        </li><li class="listitem">the currently executing object</li><li class="listitem">the target object</li><li class="listitem">
          an object encapsulating the static information about the join
          point. This is also available through the special variable
          <code class="varname">thisJoinPointStaticPart</code>.</li></ul></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idm898"></a>The <code class="classname">Demo</code> class</h4></div></div></div><p>The class <code class="classname">tjp.Demo</code> in
          <code class="filename">tjp/Demo.java</code> defines two methods
          <code class="literal">foo</code> and <code class="literal">bar</code> with different
          parameter lists and return types. Both are called, with suitable
          arguments, by <code class="classname">Demo</code>'s
          <code class="function">go</code> method which was invoked from within its
          <code class="function">main</code> method.
        </p><pre class="programlisting">
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  + ")";
    }
}
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idm910"></a>The <code class="literal">GetInfo</code> aspect</h4></div></div></div><p>
          This aspect uses around advice to intercept the execution of
          methods <code class="literal">foo</code> and <code class="literal">bar</code> in
          <code class="classname">Demo</code>, and prints out information garnered
          from <code class="literal">thisJoinPoint</code> to the console.
        </p><pre class="programlisting">
aspect GetInfo {

   static final void println(String s){ System.out.println(s); }

   pointcut goCut(): cflow(this(Demo) &amp;&amp; execution(void go()));

   pointcut demoExecs(): within(Demo) &amp;&amp; execution(* *(..));

   Object around(): demoExecs() &amp;&amp; !execution(* go()) &amp;&amp; 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 &lt; args.length; i++) {
         println("  "  + i + ". " + names[i] +
             " : " +            types[i].getName() +
             " = " +            args[i]);
      }
   }
}
</pre><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idm919"></a>Defining the scope of a pointcut</h5></div></div></div><p>The pointcut <code class="function">goCut</code> is defined as

</p><pre class="programlisting">
cflow(this(Demo)) &amp;&amp; execution(void go())
</pre><p>

            so that only executions made in the control flow of
            <code class="literal">Demo.go</code> are intercepted. The control flow
            from the method <code class="literal">go</code> includes the execution of
            <code class="literal">go</code> itself, so the definition of the around
            advice includes <code class="literal">!execution(* go())</code> to
            exclude it from the set of executions advised. </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idm928"></a>Printing the class and method name</h5></div></div></div><p>
            The name of the method and that method's defining class are
            available as parts of the <a class="ulink" href="../api/org/aspectj/lang/Signature.html" target="_top">org.aspectj.lang.Signature</a>
            object returned by calling <code class="literal">getSignature()</code> on
            either <code class="literal">thisJoinPoint</code> or
            <code class="literal">thisJoinPointStaticPart</code>.
          </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="idm935"></a>Printing the parameters</h5></div></div></div><p>
            The static portions of the parameter details, the name and
            types of the parameters, can be accessed through the <a class="ulink" href="../api/org/aspectj/lang/reflect/CodeSignature.html" target="_top"><code class="literal">org.aspectj.lang.reflect.CodeSignature</code></a>
            associated with the join point. All execution join points have code
            signatures, so the cast to <code class="literal">CodeSignature</code>
            cannot fail. </p><p>
            The dynamic portions of the parameter details, the actual
            values of the parameters, are accessed directly from the
            execution join point object.
          </p></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="examples-roles"></a>Roles and Views</h3></div></div></div><p>
        (The code for this example is in
        <code class="filename"><em class="replaceable"><code>InstallDir</code></em>/examples/introduction</code>.)
      </p><p>
        Like advice, inter-type declarations are members of an aspect. They
        declare members that act as if they were defined on another class.
        Unlike advice, inter-type declarations affect not only the behavior
        of the application, but also the structural relationship between an
        application's classes.
      </p><p>
        This is crucial: Publically affecting the class structure of an
        application makes these modifications available to other components
        of the application.
      </p><p>
        Aspects can declare inter-type

        </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem">fields</li><li class="listitem">methods</li><li class="listitem">constructors</li></ul></div><p>

        and can also declare that target types

        </p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc; "><li class="listitem">implement new interfaces</li><li class="listitem">extend new classes</li></ul></div><p>
      </p><p>
        This example provides three illustrations of the use of inter-type
        declarations to encapsulate roles or views of a class. The class
        our aspect will be dealing with, <code class="classname">Point</code>, is a
        simple class with rectangular and polar coordinates. Our inter-type
        declarations will make the class <code class="classname">Point</code>, in
        turn, cloneable, hashable, and comparable. These facilities are
        provided by AspectJ without having to modify the code for the class
        <code class="classname">Point</code>.
      </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idm961"></a>The <code class="classname">Point</code> class</h4></div></div></div><p>The <code class="classname">Point</code> class defines geometric points
          whose interface includes polar and rectangular coordinates, plus some
          simple operations to relocate points. <code class="classname">Point</code>'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 <code class="classname">Point</code> 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.
        </p><p>
          The diagram below gives an overview of the aspects and their
          interaction with the class <code class="classname">Point</code>.</p><p>
          <span class="inlinemediaobject"><img src="aspects.gif"></span>
        </p><p></p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idm975"></a>The <code class="classname">CloneablePoint</code> aspect</h4></div></div></div><p>
          This first aspect is responsible for
          <code class="classname">Point</code>'s implementation of the
          <code class="classname">Cloneable</code> interface.  It declares that
          <code class="literal">Point implements Cloneable</code> with a
          <code class="literal">declare parents</code> form, and also publically
          declares a specialized <code class="literal">Point</code>'s
          <code class="literal">clone()</code> method.  In Java, all objects inherit
          the method <code class="literal">clone</code> from the class
          <code class="classname">Object</code>, but an object is not cloneable
          unless its class also implements the interface
          <code class="classname">Cloneable</code>.  In addition, classes
          frequently have requirements over and above the simple
          bit-for-bit copying that <code class="literal">Object.clone</code> does. In
          our case, we want to update a <code class="classname">Point</code>'s
          coordinate systems before we actually clone the
          <code class="classname">Point</code>. So our aspect makes sure that
          <code class="literal">Point</code> overrides
          <code class="literal">Object.clone</code> with a new method that does what
          we want.
        </p><p>
          We also define a test <code class="literal">main</code> method in the
          aspect for convenience.
        </p><pre class="programlisting">
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 );
   }
}
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idm996"></a>The <code class="classname">ComparablePoint</code> aspect</h4></div></div></div><p>
          <code class="classname">ComparablePoint</code> is responsible for
          <code class="literal">Point</code>'s implementation of the
          <code class="literal">Comparable</code> interface. </p><p>
          The interface <code class="classname">Comparable</code> defines the
          single method <code class="literal">compareTo</code> which can be use to define
          a natural ordering relation among the objects of a class that
          implement it.
        </p><p>
          <code class="classname">ComparablePoint</code> uses <code class="literal">declare
          parents</code> to declare that <code class="literal">Point implements
          Comparable</code>, and also publically declares the
          appropriate <code class="literal">compareTo(Object)</code> method: A
          <code class="classname">Point</code> <code class="literal">p1</code> is said to be
          less than another <code class="classname">Point</code><code class="literal">
          p2</code> if <code class="literal">p1</code> is closer to the
          origin.
        </p><p>
          We also define a test <code class="literal">main</code> method in the
          aspect for convenience.
        </p><pre class="programlisting">
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));
   }
}
</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idm1019"></a>The <code class="classname">HashablePoint</code> aspect</h4></div></div></div><p>
          Our third aspect is responsible for <code class="literal">Point</code>'s
          overriding of <code class="literal">Object</code>'s
          <code class="literal">equals</code> and <code class="literal">hashCode</code> methods
          in order to make <code class="literal">Point</code>s hashable.
        </p><p>
          The method <code class="literal">Object.hashCode</code> returns an 
          integer, suitable for use as a hash table key.  It is not required
          that two objects which are not equal (according to the 
          <code class="literal">equals</code> method) return different integer
          results from <code class="literal">hashCode</code> but it can
          improve performance when the integer is used as a key into a 
          data structure.  However, any two objects which are equal 
          must return the same integer value from a call to 
          <code class="literal">hashCode</code>.  Since the default implementation
          of <code class="literal">Object.equals</code> returns <code class="literal">true</code>
          only when two objects are identical, we need to redefine both
          <code class="function">equals</code> and <code class="function">hashCode</code> to work
          correctly with objects of type <code class="classname">Point</code>. For
          example, we want two <code class="classname">Point</code> objects to test
          equal when they have the same <code class="literal">x</code> and
          <code class="literal">y</code> values, or the same <code class="literal">rho</code> and
          <code class="literal">theta</code> values, not just when they refer to the same
          object. We do this by overriding the methods
          <code class="literal">equals</code> and <code class="literal">hashCode</code> in the
          class <code class="classname">Point</code>.
        </p><p>
          So <code class="classname">HashablePoint</code> declares
          <code class="literal">Point</code>'s <code class="literal">hashCode</code> and
          <code class="literal">equals</code> methods, using
          <code class="classname">Point</code>'s rectangular coordinates to
          generate a hash code and to test for equality. The
          <code class="literal">x</code> and <code class="literal">y</code> coordinates are
          obtained using the appropriate get methods, which ensure the
          rectangular coordinates are up-to-date before returning their
          values.
        </p><p>
          And again, we supply a <code class="literal">main</code> method in the
          aspect for testing.
        </p><pre class="programlisting">
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()) &amp;&amp; (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));
   }
}
</pre></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="examples-howto.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="examples.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="examples-development.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Obtaining, Compiling and Running the Examples </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Development Aspects</td></tr></table></div></body></html>
aspectj-doc 1.8.9-2 / usr / share / doc / aspectj-doc / progguide / examples-basic.html
