org.aspectj/docs/progGuideDB/semantics.xml

<appendix id="semantics" xreflabel="Semantics">

  <title>Language Semantics</title>

  <sect1 id="semantics-intro">
    <title>Introduction</title>

    <para>
      AspectJ extends Java by overlaying a concept of join points onto the
      existing Java semantics and adding a few new program elements to Java:
    </para>

    <para>
      A join point is a well-defined point in the execution of a
      program. These include method and constructor calls, field accesses and
      others described below.
    </para>

    <para>
      A pointcut picks out join points, and exposes some of the values in the
      execution context of those join points. There are several primitive
      pointcut designators, and others can be named and defined by the
      <literal>pointcut</literal> declaration.
    </para>

    <para>
      A piece of advice is code that executes at each join point in a
      pointcut. Advice has access to the values exposed by the
      pointcut. Advice is defined by <literal>before</literal>,
      <literal>after</literal>, and <literal>around</literal> declarations.
    </para>

    <para>
      Inter-type declarations form AspectJ's static crosscutting features,
      that is, is code that may change the type structure of a program, by
      adding to or extending interfaces and classes with new fields,
      constructors, or methods.  Some inter-type declarations are defined
      through an extension of usual method, field, and constructor
      declarations, and other declarations are made with a new
      <literal>declare</literal> keyword.
    </para>

    <para>
      An aspect is a crosscutting type that encapsulates pointcuts, advice,
      and static crosscutting features. By type, we mean Java's notion: a
      modular unit of code, with a well-defined interface, about which it is
      possible to do reasoning at compile time. Aspects are defined by the
      <literal>aspect</literal> declaration.
    </para>
  </sect1>

<!-- ============================== -->

  <sect1 id="semantics-joinPoints">
    <title>Join Points</title>

    <para>
      While aspects define types that crosscut, the AspectJ system does not
      allow completely arbitrary crosscutting. Rather, aspects define types
      that cut across principled points in a program's execution. These
      principled points are called join points.
    </para>

    <para>
      A join point is a well-defined point in the execution of a
      program. The join points defined by AspectJ are:
    </para>

    <variablelist>
      <varlistentry>
        <term>Method call</term>
        <listitem>
          When a method is called, not including super calls of
          non-static methods.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Method execution</term>
        <listitem>
          When the body of code for an actual method executes.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Constructor call</term>
        <listitem>
          When an object is built and that object's initial constructor is
          called (i.e., not for "super" or "this" constructor calls).  The
          object being constructed is returned at a constructor call join
          point, so its return type is considered to be the type of the
          object, and the object itself may be accessed with <literal>after
          returning</literal> advice.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Constructor execution</term>
        <listitem>
          When the body of code for an actual constructor executes, after
          its this or super constructor call.  The object being constructed
          is the currently executing object, and so may be accessed with
          the <literal>this</literal> pointcut.  The constructor execution
          join point for a constructor that calls a super constructor also
          includes any non-static initializers of enclosing class.  No
          value is returned from a constructor execution join point, so its
          return type is considered to be void.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Static initializer execution</term>
        <listitem>
          When the static initializer for a class executes.  No value is
          returned from a static initializer execution join point, so its
          return type is considered to be void.
        </listitem>
      </varlistentry>

      <varlistentry>
       <term>Object pre-initialization</term>
       <listitem>
         Before the object initialization code for a particular class runs.
         This encompasses the time between the start of its first called
         constructor and the start of its parent's constructor.  Thus, the
         execution of these join points encompass the join points of the
         evaluation of the arguments of <literal>this()</literal> and
         <literal>super()</literal> constructor calls.  No value is
         returned from an object pre-initialization join point, so its
         return type is considered to be void.
       </listitem>
      </varlistentry>

      <varlistentry>
        <term>Object initialization</term>
        <listitem>
          When the object initialization code for a particular class runs.
          This encompasses the time between the return of its parent's
          constructor and the return of its first called constructor. It
          includes all the dynamic initializers and constructors used to
          create the object.  The object being constructed is the currently
          executing object, and so may be accessed with the
          <literal>this</literal> pointcut.  No value is returned from a
          constructor execution join point, so its return type is
          considered to be void.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Field reference</term>
        <listitem>
          When a non-constant field is referenced.  [Note that references
          to constant fields (static final fields bound to a constant
          string object or primitive value) are not join points, since Java
          requires them to be inlined.]
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Field set</term>
        <listitem>
          When a field is assigned to.
          Field set join points are considered to have one argument,
          the value the field is being set to.
          No value is returned from a field set join point, so
          its return type is considered to be void.
          [Note that the initializations of constant fields (static
          final fields where the initializer is a constant string object or
          primitive value) are not join points, since Java requires their
          references to be inlined.]
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Handler execution</term>
        <listitem>
          When an exception handler executes.
          Handler execution join points are considered to have one argument,
          the exception being handled.
          No value is returned from a field set join point, so
          its return type is considered to be void.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Advice execution</term>
        <listitem>
          When the body of code for a piece of advice executes.
        </listitem>
      </varlistentry>
    </variablelist>

    <para>
      Each join point potentially has three pieces of state associated
      with it: the currently executing object, the target object, and
      an object array of arguments.  These are exposed by the three
      state-exposing pointcuts, <literal>this</literal>,
      <literal>target</literal>, and <literal>args</literal>,
      respectively.
    </para>

    <para>
      Informally, the currently executing object is the object that a
      <literal>this</literal> expression would pick out at the join
      point.  The target object is where control or attention is
      transferred to by the join point.  The arguments are those
      values passed for that transfer of control or attention. 
    </para>

    <informaltable frame="1">
      <tgroup cols="4" align="left">
        <thead valign="top">
          <row>
            <entry><emphasis role="bold">Join Point</emphasis></entry>
            <entry><emphasis role="bold">Current Object</emphasis></entry>
            <entry><emphasis role="bold">Target Object</emphasis></entry>
            <entry><emphasis role="bold">Arguments</emphasis></entry>
          </row>
       </thead>   
       <tbody>
          <row>
            <entry>Method Call</entry>
            <entry>executing object*</entry>
            <entry>target object**</entry>
            <entry>method arguments</entry>
          </row>

          <row>
            <entry>Method Execution</entry>
            <entry>executing object*</entry>
            <entry>executing object*</entry>
            <entry>method arguments</entry>
          </row>
          <row>
            <entry>Constructor Call</entry>
            <entry>executing object*</entry>
            <entry>None</entry>
            <entry>constructor arguments</entry>
          </row>

          <row>
            <entry>Constructor Execution</entry>
            <entry>executing object</entry>
            <entry>executing object</entry>
            <entry>constructor arguments</entry>
          </row>

          <row>
            <entry>Static initializer execution</entry>
            <entry>None</entry>
            <entry>None</entry>
            <entry>None</entry>
          </row>
          <row>
            <entry>Object pre-initialization</entry>
            <entry>None</entry>
            <entry>None</entry>
            <entry>constructor arguments</entry>
          </row>
          <row>
            <entry>Object initialization</entry>
            <entry>executing object</entry>
            <entry>executing object</entry>
            <entry>constructor arguments</entry>
          </row>
          <row>
            <entry>Field reference</entry>
            <entry>executing object*</entry>
            <entry>target object**</entry>
            <entry>None</entry>
          </row>
          <row>
            <entry>Field assignment</entry>
            <entry>executing object*</entry>
            <entry>target object**</entry>
            <entry>assigned value</entry>
          </row>
          <row>
            <entry>Handler execution</entry>
            <entry>executing object*</entry>
            <entry>executing object*</entry>
            <entry>caught exception</entry>
          </row>
          <row>
            <entry>Advice execution</entry>
            <entry>executing aspect</entry>
            <entry>executing aspect</entry>
            <entry>advice arguments</entry>
          </row>
	</tbody>
      </tgroup>
     </informaltable>

     <para>* There is no executing object in static contexts such as
     static method bodies or static initializers.
     </para>

     <para>** There is no target object for join points associated
     with static methods or fields. 
     </para>

  </sect1>

<!-- ============================== -->

  <sect1 id="semantics-pointcuts">
    <title>Pointcuts</title>

    <para>
      A pointcut is a program element that picks out join points and
      exposes data from the execution context of those join points.
      Pointcuts are used primarily by advice.  They can be composed with
      boolean operators to build up other pointcuts.  The primitive
      pointcuts and combinators provided by the language are:
    </para>

    <variablelist>
      <varlistentry>
        <term><literal>call(<replaceable>MethodPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each method call join point whose signature matches
          <replaceable>MethodPattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>execution(<replaceable>MethodPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each method execution join point whose signature matches
          <replaceable>MethodPattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>get(<replaceable>FieldPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each field reference join point whose signature matches
          <replaceable>FieldPattern</replaceable>.
          [Note that references to constant fields (static final
          fields bound to a constant string object or primitive value) are not
          join points, since Java requires them to be inlined.]
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>set(<replaceable>FieldPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each field set join point whose signature matches
          <replaceable>FieldPattern</replaceable>.
          [Note that the initializations of constant fields (static
          final fields where the initializer is a constant string object or
          primitive value) are not join points, since Java requires their
          references to be inlined.]
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>call(<replaceable>ConstructorPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each constructor call join point whose signature matches
          <replaceable>ConstructorPattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>execution(<replaceable>ConstructorPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each constructor execution join point whose signature matches
          <replaceable>ConstructorPattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>initialization(<replaceable>ConstructorPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each object initialization join point whose signature matches
          <replaceable>ConstructorPattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>preinitialization(<replaceable>ConstructorPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each object pre-initialization join point whose signature matches
          <replaceable>ConstructorPattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>staticinitialization(<replaceable>TypePattern</replaceable>)</literal></term>
        <listitem>
          Picks out each static initializer execution join point whose signature matches
          <replaceable>TypePattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>handler(<replaceable>TypePattern</replaceable>)</literal></term>
        <listitem>
          Picks out each exception handler join point whose signature matches
          <replaceable>TypePattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>adviceexecution()</literal></term>
        <listitem>
          Picks out all advice execution join points.
        </listitem>
      </varlistentry>


      <varlistentry>
        <term><literal>within(<replaceable>TypePattern</replaceable>)</literal></term>
        <listitem>
          Picks out each join point where the executing code is defined
          in a type matched by <replaceable>TypePattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>withincode(<replaceable>MethodPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each join point where the executing code is defined in
          a method whose signature matches
          <replaceable>MethodPattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>withincode(<replaceable>ConstructorPattern</replaceable>)</literal></term>
        <listitem>
          Picks out each join point where the executing code is defined
          in a constructor whose signature matches
          <replaceable>ConstructorPattern</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>cflow(<replaceable>Pointcut</replaceable>)</literal></term>
        <listitem>
          Picks out each join point in the control flow of any join point
          <replaceable>P</replaceable> picked out by
          <replaceable>Pointcut</replaceable>, including
          <replaceable>P</replaceable> itself.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>cflowbelow(<replaceable>Pointcut</replaceable>)</literal></term>
        <listitem>
          Picks out each join point in the control flow of any join point
          <replaceable>P</replaceable> picked out by
          <replaceable>Pointcut</replaceable>, but not
          <replaceable>P</replaceable> itself.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>this(<replaceable>Type</replaceable> or <replaceable>Id</replaceable>)</literal></term>
        <listitem>
          Picks out each join point where the currently executing object
          (the object bound to <literal>this</literal>) is an instance of
          <replaceable>Type</replaceable>, or of the type of the
          identifier <replaceable>Id</replaceable> (which must be bound in the enclosing
          advice or pointcut definition).
          Will not match any join points from static contexts.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>target(<replaceable>Type</replaceable> or <replaceable>Id</replaceable>)</literal></term>
        <listitem>
          Picks out each join point where the target object (the object
          on which a call or field operation is applied to) is an instance of
          <replaceable>Type</replaceable>, or of the type of the identifier
          <replaceable>Id</replaceable> (which must be bound in the enclosing
          advice or pointcut definition).
          Will not match any calls, gets, or sets of static members.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>args(<replaceable>Type</replaceable> or <replaceable>Id</replaceable>, ...)</literal></term>
        <listitem>
          Picks out each join point where the arguments are instances of
          a type of the appropriate type pattern or identifier.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal><replaceable>PointcutId</replaceable>(<replaceable>TypePattern</replaceable> or <replaceable>Id</replaceable>, ...)</literal></term>
        <listitem>
          Picks out each join point that is picked out by the
          user-defined pointcut designator named by
          <replaceable>PointcutId</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>if(<replaceable>BooleanExpression</replaceable>)</literal></term>
        <listitem>
          Picks out each join point where the boolean expression
          evaluates to <literal>true</literal>.  The boolean expression used
          can only access static members, parameters exposed by the enclosing
          pointcut or advice, and <literal>thisJoinPoint</literal> forms.  In
          particular, it cannot call non-static methods on the aspect or
		  use return values or exceptions exposed by after advice.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>! <replaceable>Pointcut</replaceable></literal></term>
        <listitem>
          Picks out each join point that is not picked out by
          <replaceable>Pointcut</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal><replaceable>Pointcut0</replaceable> <![CDATA[&&]]> <replaceable>Pointcut1</replaceable></literal></term>
        <listitem>
          Picks out each join points that is picked out by both
          <replaceable>Pointcut0</replaceable> and
          <replaceable>Pointcut1</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal><replaceable>Pointcut0</replaceable> || <replaceable>Pointcut1</replaceable></literal></term>
        <listitem>
          Picks out each join point that is picked out by either
          pointcuts. <replaceable>Pointcut0</replaceable> or
          <replaceable>Pointcut1</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>( <replaceable>Pointcut</replaceable> )</literal></term>
        <listitem>
          Picks out each join points picked out by
          <replaceable>Pointcut</replaceable>.
        </listitem>
      </varlistentry>
    </variablelist>

    <sect2>
      <title>Pointcut definition</title>

      <para>
        Pointcuts are defined and named by the programmer with the
        <literal>pointcut</literal> declaration.
      </para>

<programlisting>
  pointcut publicIntCall(int i):
      call(public * *(int)) <![CDATA[&&]]> args(i);
</programlisting>

      <para>
        A named pointcut may be defined in either a class or aspect, and is
        treated as a member of the class or aspect where it is found.  As a
        member, it may have an access modifier such as
        <literal>public</literal> or <literal>private</literal>.
      </para>

<programlisting>
  class C {
      pointcut publicCall(int i):
	  call(public * *(int)) <![CDATA[&&]]> args(i);
  }

  class D {
      pointcut myPublicCall(int i):
	  C.publicCall(i) <![CDATA[&&]]> within(SomeType);
  }
</programlisting>

      <para>
        Pointcuts that are not final may be declared abstract, and defined
        without a body.  Abstract pointcuts may only be declared within
        abstract aspects.
      </para>

<programlisting>
  abstract aspect A {
      abstract pointcut publicCall(int i);
  }
</programlisting>

      <para>
        In such a case, an extending aspect may override the abstract
        pointcut.
      </para>

<programlisting>
  aspect B extends A {
      pointcut publicCall(int i): call(public Foo.m(int)) <![CDATA[&&]]> args(i);
  }
</programlisting>

      <para>
        For completeness, a pointcut with a declaration may be declared
        <literal>final</literal>.
      </para>

      <para>
        Though named pointcut declarations appear somewhat like method
        declarations, and can be overridden in subaspects, they cannot be
        overloaded. It is an error for two pointcuts to be named with the
        same name in the same class or aspect declaration.
      </para>

      <para>
        The scope of a named pointcut is the enclosing class declaration.
        This is different than the scope of other members; the scope of
        other members is the enclosing class <emphasis>body</emphasis>.
        This means that the following code is legal:
      </para>

<programlisting>
  aspect B percflow(publicCall()) {
      pointcut publicCall(): call(public Foo.m(int));
  }
</programlisting>
    </sect2>

    <sect2>
      <title>Context exposure</title>

      <para>
        Pointcuts have an interface; they expose some parts of the
        execution context of the join points they pick out. For example,
        the PublicIntCall above exposes the first argument from the
        receptions of all public unary integer methods.  This context is
        exposed by providing typed formal parameters to named pointcuts and
        advice, like the formal parameters of a Java method. These formal
        parameters are bound by name matching.
      </para>

      <para>
        On the right-hand side of advice or pointcut declarations, in
        certain pointcut designators, a Java identifier is allowed in place
        of a type or collection of types.  The pointcut designators that
        allow this are <literal>this</literal>, <literal>target</literal>,
        and <literal>args</literal>.  In all such cases, using an
        identifier rather than a type does two things.  First, it selects
        join points as based on the type of the formal parameter.  So the
        pointcut
      </para>

<programlisting>
  pointcut intArg(int i): args(i);
</programlisting>

      <para>
        picks out join points where an <literal>int</literal> (or
        a <literal>byte</literal>, <literal>short</literal>, or
        <literal>char</literal>; anything assignable to an
        <literal>int</literal>) is being passed as an argument.
        Second, though, it makes the value of that argument
        available to the enclosing advice or pointcut.  
      </para>

      <para>
        Values can be exposed from named pointcuts as well, so
      </para>

<programlisting>
  pointcut publicCall(int x): call(public *.*(int)) <![CDATA[&&]]> intArg(x);
  pointcut intArg(int i): args(i);
</programlisting>

      <para>
        is a legal way to pick out all calls to public methods accepting an
        int argument, and exposing that argument.
      </para>

      <para>
        There is one special case for this kind of exposure.  Exposing an
        argument of type Object will also match primitive typed arguments,
        and expose a "boxed" version of the primitive.  So,
      </para>

<programlisting>
  pointcut publicCall(): call(public *.*(..)) <![CDATA[&&]]> args(Object);
</programlisting>

      <para>
        will pick out all unary methods that take, as their only argument,
        subtypes of Object (i.e., not primitive types like
        <literal>int</literal>), but
      </para>

<programlisting>
  pointcut publicCall(Object o): call(public *.*(..)) <![CDATA[&&]]> args(o);
</programlisting>

      <para>
        will pick out all unary methods that take any argument: And if the
        argument was an <literal>int</literal>, then the value passed to
        advice will be of type <literal>java.lang.Integer</literal>.
      </para>

      <para>
        The "boxing" of the primitive value is based on the
        <emphasis>original</emphasis> primitive type.  So in the
        following program
      </para>

<programlisting>
  public class InstanceOf {

    public static void main(String[] args) {
      doInt(5);
    }

    static void doInt(int i) {  }
  }

  aspect IntToLong {
    pointcut el(long l) : 
        execution(* doInt(..)) <![CDATA[&&]]> args(l);

    before(Object o) : el(o) {
         System.out.println(o.getClass());
    }
  }
</programlisting>

      <para>
        The pointcut will match and expose the integer argument,
        but it will expose it as an <literal>Integer</literal>,
        not a <literal>Long</literal>.
      </para>

    </sect2>

    <sect2>
      <title>Primitive pointcuts</title>

      <sect3>
        <title>Method-related pointcuts</title>

        <para>AspectJ provides two primitive pointcut designators designed to
        capture method call and execution join points. </para>

        <itemizedlist>
        <listitem><literal>call(<replaceable>MethodPattern</replaceable>)</literal></listitem>
        <listitem><literal>execution(<replaceable>MethodPattern</replaceable>)</literal></listitem>
        </itemizedlist>
      </sect3>

      <sect3>
        <title>Field-related pointcuts</title>

        <para>
          AspectJ provides two primitive pointcut designators designed to
          capture field reference and set join points:
        </para>

        <itemizedlist>
        <listitem><literal>get(<replaceable>FieldPattern</replaceable>)</literal></listitem>
        <listitem><literal>set(<replaceable>FieldPattern</replaceable>)</literal></listitem>
        </itemizedlist>

        <para>
          All set join points are treated as having one argument, the value the
          field is being set to, so at a set join point, that value can be
          accessed with an <literal>args</literal> pointcut.  So an aspect
          guarding a static integer variable x declared in type T might be written as
        </para>

<programlisting><![CDATA[
  aspect GuardedX {
      static final int MAX_CHANGE = 100;
      before(int newval): set(static int T.x) && args(newval) {
	  if (Math.abs(newval - T.x) > MAX_CHANGE)
	      throw new RuntimeException();
      }
  }
]]></programlisting>

      </sect3>

      <sect3>
        <title>Object creation-related pointcuts</title>

        <para>
          AspectJ provides primitive pointcut designators designed to
          capture the initializer execution join points of objects.
        </para>

        <itemizedlist>
          <listitem><literal>call(<replaceable>ConstructorPattern</replaceable>)</literal></listitem>
          <listitem><literal>execution(<replaceable>ConstructorPattern</replaceable>)</literal></listitem>
          <listitem><literal>initialization(<replaceable>ConstructorPattern</replaceable>)</literal></listitem>
          <listitem><literal>preinitialization(<replaceable>ConstructorPattern</replaceable>)</literal></listitem>
        </itemizedlist>

      </sect3>

      <sect3>
        <title>Class initialization-related pointcuts</title>

        <para>
          AspectJ provides one primitive pointcut designator to pick out
          static initializer execution join points.
        </para>

        <itemizedlist>
        <listitem><literal>staticinitialization(<replaceable>TypePattern</replaceable>)</literal></listitem>
        </itemizedlist>

      </sect3>

      <sect3>
        <title>Exception handler execution-related pointcuts</title>

        <para>
          AspectJ provides one primitive pointcut designator to capture
          execution of exception handlers:
        </para>

        <itemizedlist>
        <listitem><literal>handler(<replaceable>TypePattern</replaceable>)</literal></listitem>
        </itemizedlist>

        <para>
          All handler join points are treated as having one argument, the value
          of the exception being handled.  That value can be accessed with an
          <literal>args</literal> pointcut.  So an aspect used to put
          <literal>FooException</literal> objects into some normal form before
          they are handled could be written as
        </para>

<programlisting>
  aspect NormalizeFooException {
      before(FooException e): handler(FooException) <![CDATA[&&]]> args(e) {
	  e.normalize();
      }
  }
</programlisting>

      </sect3>

      <sect3>
        <title>Advice execution-related pointcuts</title>

        <para>
          AspectJ provides one primitive pointcut designator to capture
          execution of advice
        </para>

        <itemizedlist>
          <listitem><literal>adviceexecution()</literal></listitem>
        </itemizedlist>

        <para>
          This can be used, for example, to filter out any join point in the
          control flow of advice from a particular aspect.
        </para>

<programlisting>
  aspect TraceStuff {
      pointcut myAdvice(): adviceexecution() <![CDATA[&&]]> within(TraceStuff);

      before(): call(* *(..)) <![CDATA[&&]]> !cflow(myAdvice) {
	  // do something
      }
  }
</programlisting>

      </sect3>

      <sect3>
        <title>State-based pointcuts</title>

        <para>
          Many concerns cut across the dynamic times when an object of a
          particular type is executing, being operated on, or being passed
          around.  AspectJ provides primitive pointcuts that capture join
          points at these times.  These pointcuts use the dynamic types of
          their objects to pick out join points.  They may also be used to
          expose the objects used for discrimination.
        </para>

        <itemizedlist>
          <listitem><literal>this(<replaceable>Type</replaceable> or <replaceable>Id</replaceable>)</literal></listitem>
          <listitem><literal>target(<replaceable>Type</replaceable> or <replaceable>Id</replaceable>)</literal></listitem>
        </itemizedlist>

        <para>
          The <literal>this</literal> pointcut picks out each join point where
          the currently executing object (the object bound to
          <literal>this</literal>) is an instance of a particular type.  The
          <literal>target</literal> pointcut picks out each join point where
          the target object (the object on which a method is called or a field
          is accessed) is an instance of a particular type.  Note that
          <literal>target</literal> should be understood to be the object the
          current join point is transfering control to.  This means that the
          target object is the same as the current object at a method execution
          join point, for example, but may be different at a method call join
          point.
        </para>

        <itemizedlist>
          <listitem><literal>args(<replaceable>Type</replaceable> or <replaceable>Id</replaceable> or "..", ...)</literal></listitem>
        </itemizedlist>

        <para>
          The args pointcut picks out each join point where the arguments are
          instances of some types.  Each element in the comma-separated list is
          one of four things.  If it is a type name, then the argument in that
          position must be an instance of that type. If it is an identifier,
          then that identifier must be bound in the enclosing advice or
          pointcut declaration, and so the argument in that position must be an
          instance of the type of the identifier (or of any type if the
          identifier is typed to Object).  If it is the "*" wildcard, then any
          argument will match, and if it is the special wildcard "..", then any
          number of arguments will match, just like in signature patterns.  So the
          pointcut
        </para>

<programlisting>
  args(int, .., String)
</programlisting>

        <para>
          will pick out all join points where the first argument is an
          <literal>int</literal> and the last is a <literal>String</literal>.
        </para>

      </sect3>

      <sect3>
        <title>Control flow-based pointcuts</title>

        <para>
          Some concerns cut across the control flow of the program. The
          <literal>cflow</literal> and <literal>cflowbelow</literal> primitive
          pointcut designators capture join points based on control flow.
        </para>

        <itemizedlist>
          <listitem><literal>cflow(<replaceable>Pointcut</replaceable>)</literal></listitem>
          <listitem><literal>cflowbelow(<replaceable>Pointcut</replaceable>)</literal></listitem>
        </itemizedlist>

        <para>
          The <literal>cflow</literal> pointcut picks out all join points that
          occur between entry and exit of each join point
          <replaceable>P</replaceable> picked out by
          <replaceable>Pointcut</replaceable>, including
          <replaceable>P</replaceable> itself.  Hence, it picks out the join
          points <emphasis>in</emphasis> the control flow of the join points
          picked out by <replaceable>Pointcut</replaceable>.
        </para>

        <para>
          The <literal>cflowbelow</literal> pointcut picks out all join points
          that occur between entry and exit of each join point
          <replaceable>P</replaceable> picked out by
          <replaceable>Pointcut</replaceable>, but not including
          <replaceable>P</replaceable> itself.  Hence, it picks out the join
          points <emphasis>below</emphasis> the control flow of the join points
          picked out by <replaceable>Pointcut</replaceable>.
        </para>

        <sect4>
          <title>Context exposure from control flows</title>

          <para>
            The <literal>cflow</literal> and
            <literal>cflowbelow</literal> pointcuts may expose context
            state through enclosed <literal>this</literal>,
            <literal>target</literal>, and <literal>args</literal>
            pointcuts. 
          </para>

          <para>
	    Anytime such state is accessed, it is accessed through the
	    <emphasis>most recent</emphasis> control flow that
	    matched.   So the "current arg" that would be printed by
	    the following program is zero, even though it is in many
	    control flows.
          </para>

<programlisting>
class Test {
    public static void main(String[] args) {
        fact(5);
    }
    static int fact(int x) {
        if (x == 0) {
            System.err.println("bottoming out");
            return 1;
        }
        else return x * fact(x - 1);
    }
}

aspect A {
    pointcut entry(int i): call(int fact(int)) <![CDATA[&&]]> args(i);
    pointcut writing(): call(void println(String)) <![CDATA[&&]]> ! within(A);
    
    before(int i): writing() <![CDATA[&&]]> cflow(entry(i)) {
        System.err.println("Current arg is " + i);
    }
}
</programlisting>

          <para>
            It is an error to expose such state through
            <emphasis>negated</emphasis> control flow pointcuts, such
            as within <literal>!
            cflowbelow(<replaceable>P</replaceable>)</literal>.
          </para>

        </sect4>
      </sect3>

      <sect3>
        <title>Program text-based pointcuts</title>

        <para>
          While many concerns cut across the runtime structure of the program,
          some must deal with the lexical structure. AspectJ allows aspects to
          pick out join points based on where their associated code is defined.
        </para>

        <itemizedlist>
        <listitem><literal>within(<replaceable>TypePattern</replaceable>)</literal></listitem>
        <listitem><literal>withincode(<replaceable>MethodPattern</replaceable>)</literal></listitem>
        <listitem><literal>withincode(<replaceable>ConstructorPattern</replaceable>)</literal></listitem>
        </itemizedlist>

        <para>
          The <literal>within</literal> pointcut picks out each join point
          where the code executing is defined in the declaration of one of the
          types in <replaceable>TypePattern</replaceable>. This includes the
          class initialization, object initialization, and method and
          constructor execution join points for the type, as well as any join
          points associated with the statements and expressions of the type.
          It also includes any join points that are associated with code in a
          type's nested types, and that type's default constructor, if there is
          one.
        </para>

        <para>
          The <literal>withincode</literal> pointcuts picks out each join point
          where the code executing is defined in the declaration of a
          particular method or constructor.  This includes the method or
          constructor execution join point as well as any join points
          associated with the statements and expressions of the method or
          constructor.  It also includes any join points that are associated
          with code in a method or constructor's local or anonymous types.
        </para>

      </sect3>

      <sect3>
        <title>Expression-based pointcuts</title>

        <itemizedlist>
        <listitem><literal>if(<replaceable>BooleanExpression</replaceable>)</literal></listitem>
        </itemizedlist>

        <para>
          The if pointcut picks out join points based on a dynamic property.
          It's syntax takes an expression, which must evaluate to a boolean
          true or false.  Within this expression, the
          <literal>thisJoinPoint</literal> object is available.  So one
          (extremely inefficient) way of picking out all call join points would
          be to use the pointcut
        </para>

<programlisting>
  if(thisJoinPoint.getKind().equals("call"))
</programlisting>

	    <para>
	    	Note that the order of evaluation for pointcut expression 
	    	components at a join point is undefined. Writing <literal>if</literal> 
	    	pointcuts that have side-effects is considered bad style and may also 
	    	lead to potentially confusing or even changing behavior with regard 
	    	to when or if the test code will run.
	    </para>
      </sect3>
    </sect2>

    <sect2>
      <title>Signatures</title>

      <para>
        One very important property of a join point is its signature, which is
        used by many of AspectJ's pointcut designators to select particular
        join points.
      </para>

      <sect3>
        <title>Methods</title>

        <para>
          Join points associated with methods typically have method signatures,
          consisting of a method name, parameter types, return type, the types of
          the declared (checked) exceptions, and some type that the method could
          be called on (below called the "qualifying type").
        </para>

        <para>
          At a method call join point, the signature is a method signature whose
          qualifying type is the static type used to <emphasis>access</emphasis>
          the method.  This means that the signature for the join point created
          from the call <literal>((Integer)i).toString()</literal> is different
          than that for the call <literal>((Object)i).toString()</literal>, even
          if <literal>i</literal> is the same variable.
        </para>

        <para>
          At a method execution join point, the signature is a method signature
          whose qualifying type is the declaring type of the method.
        </para>

      </sect3>

      <sect3>
        <title>Fields</title>

        <para>
          Join points associated with fields typically have field signatures,
          consisting of a field name and a field type.  A field reference join
          point has such a signature, and no parameters.  A field set join point
          has such a signature, but has a has a single parameter whose type is
          the same as the field type.
        </para>

      </sect3>

      <sect3>
        <title>Constructors</title>

        <para>
          Join points associated with constructors typically have constructor
          signatures, consisting of a parameter types, the types of the declared
          (checked) exceptions, and the declaring type.
        </para>

        <para>
          At a constructor call join point, the signature is the constructor
          signature of the called constructor.  At a constructor execution join
          point, the signature is the constructor signature of the currently
          executing constructor.
        </para>

        <para>
          At object initialization and pre-initialization join points, the
          signature is the constructor signature for the constructor that started
          this initialization: the first constructor entered during this type's
          initialization of this object.
        </para>
      </sect3>

      <sect3>
        <title>Others</title>

        <para>
          At a handler execution join point, the signature is composed of the
          exception type that the handler handles.
        </para>

        <para>
          At an advice execution join point, the signature is composed of the
          aspect type, the parameter types of the advice, the return type (void
          for all but around advice) and the types of the declared (checked)
          exceptions.
        </para>
      </sect3>
    </sect2>

<!-- ============================== -->

    <sect2>
      <title>Matching</title>

      <para>
        The <literal>withincode</literal>, <literal>call</literal>,
        <literal>execution</literal>, <literal>get</literal>, and
        <literal>set</literal> primitive pointcut designators all use signature
        patterns to determine the join points they describe. A signature
        pattern is an abstract description of one or more join-point
        signatures. Signature patterns are intended to match very closely the
        same kind of things one would write when declaring individual members
        and constructors.
      </para>

      <para>
        Method declarations in Java include method names, method parameters,
        return types, modifiers like static or private, and throws clauses,
        while constructor declarations omit the return type and replace the
        method name with the class name. The start of a particular method
        declaration, in class <literal>Test</literal>, for example, might be
      </para>


<programlisting>
  class C {
      public final void foo() throws ArrayOutOfBoundsException { ... }
  }
</programlisting>

      <para>
        In AspectJ, method signature patterns have all these, but most elements
        can be replaced by wildcards. So
      </para>


<programlisting>
  call(public final void C.foo() throws ArrayOutOfBoundsException)
</programlisting>

      <para>
        picks out call join points to that method, and the pointcut
      </para>

<programlisting>
  call(public final void *.*() throws ArrayOutOfBoundsException)
</programlisting>


      <para>
        picks out all call join points to methods, regardless of their name
        name or which class they are defined on, so long as they take no
        arguments, return no value, are both <literal>public</literal> and
        <literal>final</literal>, and are declared to throw
        <literal>ArrayOutOfBounds</literal> exceptions.
      </para>

      <para>
        The defining type name, if not present, defaults to *, so another way
        of writing that pointcut would be
      </para>

<programlisting>
  call(public final void *() throws ArrayOutOfBoundsException)
</programlisting>

      <para>
        Formal parameter lists can use the wildcard <literal>..</literal> to
        indicate zero or more arguments, so
      </para>

<programlisting>
  execution(void m(..))
</programlisting>

      <para>
        picks out execution join points for void methods named
        <literal>m</literal>, of any number of arguments, while
      </para>

<programlisting>
  execution(void m(.., int))
</programlisting>

      <para>
        picks out execution join points for void methods named
        <literal>m</literal> whose last parameter is of type
        <literal>int</literal>.
      </para>

      <para>
        The modifiers also form part of the signature pattern. If an AspectJ
        signature pattern should match methods without a particular modifier,
        such as all non-public methods, the appropriate modifier should be
        negated with the <literal>!</literal> operator. So,
      </para>

<programlisting>
  withincode(!public void foo())
</programlisting>

      <para>
        picks out all join points associated with code in null non-public
        void methods named <literal>foo</literal>, while
      </para>

<programlisting>
  withincode(void foo())
</programlisting>

      <para>
        picks out all join points associated with code in null void methods
        named <literal>foo</literal>, regardless of access modifier.
      </para>

      <para>
        Method names may contain the * wildcard, indicating any number of
        characters in the method name.  So
      </para>

<programlisting>
  call(int *())
</programlisting>

      <para>
        picks out all call join points to <literal>int</literal> methods
        regardless of name, but
      </para>

<programlisting>
  call(int get*())
</programlisting>

      <para>
        picks out all call join points to <literal>int</literal> methods
        where the method name starts with the characters "get".
      </para>

      <para>
        AspectJ uses the <literal>new</literal> keyword for constructor
        signature patterns rather than using a particular class name. So the
        execution join points of private null constructor of a class C
        defined to throw an ArithmeticException can be picked out with
      </para>

<programlisting>
  execution(private C.new() throws ArithmeticException)
</programlisting>

      <sect3>
        <title>Matching based on the declaring type</title>

        <para>
        The signature-matching pointcuts all specify a declaring type,
        but the meaning varies slightly for each join point signature,
        in line with Java semantics.
        </para>

        <para>
        When matching for pointcuts <literal>withincode</literal>, 
        <literal>get</literal>, and <literal>set</literal>, the declaring
        type is the class that contains the declaration.
        </para>

        <para>
        When matching method-call join points, the 
        declaring type is the static type used to access the method.
        A common mistake is to specify a declaring type for the 
        <literal>call</literal> pointcut that is a subtype of the 
        originally-declaring type. For example, given the class
        </para>

<programlisting>
  class Service implements Runnable {
    public void run() { ... }
  } 
</programlisting>

        <para>
        the following pointcut
        </para>

<programlisting>
  call(void Service.run())
</programlisting>

        <para>
        would fail to pick out the join point for the code
        </para>

<programlisting>
  ((Runnable) new Service()).run();
</programlisting>

        <para>
        Specifying the originally-declaring type is correct, but would
        pick out any such call (here, calls to the <literal>run()</literal>
        method of any Runnable).  
        In this situation, consider instead picking out the target type:
        </para>

<programlisting>
  call(void run()) &amp;&amp; target(Service)
</programlisting>

        <para>
        When matching method-execution join points, 
        if the execution pointcut method signature specifies a declaring type, 
        the pointcut will only match methods declared in that type, or methods 
        that override methods declared in or inherited by that type.
        So the pointcut
      </para>

<programlisting>
  execution(public void Middle.*())
</programlisting>

      <para>
      picks out all method executions for public methods returning void
      and having no arguments that are either declared in, or inherited by, 
      Middle, even if those methods are overridden in a subclass of Middle. 
      So the pointcut would pick out the method-execution join point
      for Sub.m() in this code:
      </para>

<programlisting>
  class Super {
    protected void m() { ... }
  }
  class Middle extends Super {
  }
  class Sub extends Middle {
    public void m() { ... }
  }
</programlisting>

      </sect3>

      <sect3>
        <title>Matching based on the throws clause</title>

        <para>
          Type patterns may be used to pick out methods and constructors
          based on their throws clauses. This allows the following two
          kinds of extremely wildcarded pointcuts:
        </para>

<programlisting>
  pointcut throwsMathlike():
      // each call to a method with a throws clause containing at least
      // one exception exception with "Math" in its name.
      call(* *(..) throws *..*Math*);

  pointcut doesNotThrowMathlike():
      // each call to a method with a throws clause containing no
      // exceptions with "Math" in its name.
      call(* *(..) throws !*..*Math*);
</programlisting>

        <para>
          A <replaceable>ThrowsClausePattern</replaceable> is a comma-separated list of
          <replaceable>ThrowsClausePatternItem</replaceable>s, where

          <variablelist>
            <varlistentry>
              <term><replaceable>ThrowsClausePatternItem</replaceable> :</term>
              <listitem>
                <literal>[ ! ]
                <replaceable>TypeNamePattern</replaceable></literal>
              </listitem>
            </varlistentry>
          </variablelist>
        </para>

        <para>
          A <replaceable>ThrowsClausePattern</replaceable> matches the
          throws clause of any code member signature. To match, each
          <literal>ThrowsClausePatternItem</literal> must
          match the throws clause of the member in question. If any item
          doesn't match, then the whole pattern doesn't match.
        </para>

        <para>
          If a ThrowsClausePatternItem begins with "!", then it matches a
          particular throws clause if and only if <emphasis>none</emphasis>
          of the types named in the throws clause is matched by the
          <literal>TypeNamePattern</literal>.
        </para>

        <para>
          If a <replaceable>ThrowsClausePatternItem</replaceable> does not
          begin with "!", then it matches a throws clause if and only if
          <emphasis>any</emphasis> of the types named in the throws clause
          is matched by the <emphasis>TypeNamePattern</emphasis>.
        </para>

        <para>
          The rule for "!" matching has one potentially surprising
          property, in that these two pointcuts

          <itemizedlist>
            <listitem> call(* *(..) throws !IOException) </listitem>
            <listitem> call(* *(..) throws (!IOException)) </listitem>
          </itemizedlist>

          will match differently on calls to

          <blockquote>
            <literal>
              void m() throws RuntimeException, IOException {}
            </literal>
          </blockquote>
        </para>

        <para>
          [1] will NOT match the method m(), because method m's throws
          clause declares that it throws IOException. [2] WILL match the
          method m(), because method m's throws clause declares the it
          throws some exception which does not match IOException,
          i.e. RuntimeException.
        </para>
      </sect3>
    </sect2>

    <sect2>
      <title>Type patterns</title>

      <para>
        Type patterns are a way to pick out collections of types and use them
        in places where you would otherwise use only one type.  The rules for
        using type patterns are simple.
      </para>

      <sect3>
        <title>Exact type pattern</title>

        <para>
          First, all type names are also type patterns.  So
          <literal>Object</literal>, <literal>java.util.HashMap</literal>,
          <literal>Map.Entry</literal>, <literal>int</literal> are all type
          patterns.
        </para>

	<para>
	  If a type pattern is an exact type - if it doesn't
	  include a wildcard - then the matching works just
	  like normal type lookup in Java: </para>

        <itemizedlist>
          <listitem>Patterns that have the same names as
          primitive types (like <literal>int</literal>) match
          those primitive types.</listitem>

          <listitem>Patterns that are qualified by package names
          (like <literal>java.util.HashMap</literal>) match types
          in other packages.
          </listitem>

          <listitem>Patterns that are not qualified (like
          <literal>HashMap</literal>) match types that are
          resolved by Java's normal scope rules.  So, for
          example, <literal>HashMap</literal> might match a
          package-level type in the same package or a type that
          have been imported with java's
          <literal>import</literal> form.  But it would not match
          <literal>java.util.HashMap</literal> unless the aspect
          were in <literal>java.util</literal> or the type had
          been imported.
          </listitem> 
        </itemizedlist>

        <para>
	  So exact type patterns match based on usual Java scope
	  rules.
        </para>

      </sect3>

      <sect3>
        <title>Type name patterns</title>

        <para>
          There is a special type name, *, which is also a type pattern.  * picks out all
          types, including primitive types.  So
        </para>

<programlisting>
  call(void foo(*))
</programlisting>

        <para>
          picks out all call join points to void methods named foo, taking one
          argument of any type.
        </para>

        <para>
          Type names that contain the two wildcards "*" and
          "<literal>..</literal>" are also type patterns.  The * wildcard matches
          zero or more characters characters except for ".", so it can be used
          when types have a certain naming convention.  So
        </para>

<programlisting>
  handler(java.util.*Map)
</programlisting>

        <para>
          picks out the types java.util.Map and java.util.java.util.HashMap,
          among others, and
        </para>

<programlisting>
  handler(java.util.*)
</programlisting>

        <para>
          picks out all types that start with "<literal>java.util.</literal>" and
          don't have any more "."s, that is, the types in the
          <literal>java.util</literal> package, but not inner types
          (such as java.util.Map.Entry).
        </para>

        <para>
          The "<literal>..</literal>" wildcard matches any sequence of
          characters that start and end with a ".", so it can be used
          to pick out all types in any subpackage, or all inner types.  So
        </para>

<programlisting>
  within(com.xerox..*)
</programlisting>

        <para>
          picks out all join points where the code is in any 
          declaration of a type whose name begins with "<literal>com.xerox.</literal>".
        </para>

	<para>
	  Type patterns with wildcards do not depend on Java's
	  usual scope rules - they match against all types
	  available to the weaver, not just those that are
	  imported into an Aspect's declaring file.
        </para>

      </sect3>

      <sect3>
        <title>Subtype patterns</title>

        <para>
          It is possible to pick out all subtypes of a type (or a collection of
          types) with the "+" wildcard.  The "+" wildcard follows immediately a
          type name pattern.  So, while
        </para>

<programlisting>
  call(Foo.new())
</programlisting>

        <para>
          picks out all constructor call join points where an instance of exactly
          type Foo is constructed,
        </para>

<programlisting>
  call(Foo+.new())
</programlisting>

        <para>
          picks out all constructor call join points where an instance of any
          subtype of Foo (including Foo itself) is constructed, and the unlikely
        </para>

<programlisting>
  call(*Handler+.new())
</programlisting>

        <para>
          picks out all constructor call join points where an instance of any
          subtype of any type whose name ends in "Handler" is constructed.
        </para>

      </sect3>

      <sect3>
        <title>Array type patterns</title>

        <para>
          A type name pattern or subtype pattern can be followed by one or more
          sets of square brackets to make array type patterns.  So
          <literal>Object[]</literal> is an array type pattern, and so is
          <literal>com.xerox..*[][]</literal>, and so is
          <literal>Object+[]</literal>.
        </para>
      </sect3>

      <sect3>
        <title>Type patterns</title>

        <para>
          Type patterns are built up out of type name patterns, subtype patterns,
          and array type patterns, and constructed with boolean operators
          <literal><![CDATA[&&]]></literal>, <literal>||</literal>, and
          <literal>!</literal>.  So
        </para>

<programlisting>
  staticinitialization(Foo || Bar)
</programlisting>

        <para>
          picks out the static initializer execution join points of either Foo or Bar,
          and
        </para>

<programlisting>
  call((Foo+ <![CDATA[&&]]> ! Foo).new(..))
</programlisting>

        <para>
          picks out the constructor call join points when a subtype of Foo, but
          not Foo itself, is constructed.
        </para>
      </sect3>
    </sect2>

    <sect2>
      <title>Pattern Summary</title>

      <para>
        Here is a summary of the pattern syntax used in AspectJ:
      </para>

<programlisting>
MethodPattern = 
  [ModifiersPattern] TypePattern 
        [TypePattern . ] IdPattern (TypePattern | ".." , ... ) 
        [ throws ThrowsPattern ]
ConstructorPattern = 
  [ModifiersPattern ] 
        [TypePattern . ] new (TypePattern | ".." , ...) 
        [ throws ThrowsPattern ]
FieldPattern = 
  [ModifiersPattern] TypePattern [TypePattern . ] IdPattern
ThrowsPattern = 
  [ ! ] TypePattern , ...
TypePattern = 
    IdPattern [ + ] [ [] ... ]
    | ! TypePattern
    | TypePattern <![CDATA[&&]]> TypePattern
    | TypePattern || TypePattern
    | ( TypePattern )  
IdPattern =
  Sequence of characters, possibly with special * and .. wildcards
ModifiersPattern =
  [ ! ] JavaModifier  ...
</programlisting>

    </sect2>

  </sect1>

<!-- ============================== -->

  <sect1 id="semantics-advice">
    <title>Advice</title>

    <para>
      Each piece of advice is of the form

      <blockquote>
        <literal>[ strictfp ] <replaceable>AdviceSpec</replaceable> [
        throws <replaceable>TypeList</replaceable> ] :
        <replaceable>Pointcut</replaceable> {
        <replaceable>Body</replaceable> } </literal>
      </blockquote>

      where <replaceable>AdviceSpec</replaceable> is one of
    </para>

    <itemizedlist>
      <listitem>
        <literal>before( <replaceable>Formals</replaceable> ) </literal>
      </listitem>
      <listitem>
        <literal>after( <replaceable>Formals</replaceable> ) returning
        [ ( <replaceable>Formal</replaceable> ) ] </literal>
      </listitem>
      <listitem>
        <literal>after( <replaceable>Formals</replaceable> ) throwing [
        ( <replaceable>Formal</replaceable> ) ] </literal>
      </listitem>
      <listitem>
        <literal>after( <replaceable>Formals</replaceable> ) </literal>
      </listitem>
      <listitem>
        <literal><replaceable>Type</replaceable>
        around( <replaceable>Formals</replaceable> )</literal>
      </listitem>
    </itemizedlist>

    <para>
      Advice defines crosscutting behavior.  It is defined in terms of
      pointcuts. The code of a piece of advice runs at every join point
      picked out by its pointcut. Exactly how the code runs depends on the
      kind of advice.
    </para>

    <para>
      AspectJ supports three kinds of advice. The kind of advice determines how
      it interacts with the join points it is defined over. Thus AspectJ
      divides advice into that which runs before its join points, that which
      runs after its join points, and that which runs in place of (or "around")
      its join points.
    </para>

    <para>
      While before advice is relatively unproblematic, there can be three
      interpretations of after advice: After the execution of a join point
      completes normally, after it throws an exception, or after it does either
      one. AspectJ allows after advice for any of these situations.
    </para>

<programlisting>
  aspect A {
      pointcut publicCall(): call(public Object *(..));
      after() returning (Object o): publicCall() {
	  System.out.println("Returned normally with " + o);
      }
      after() throwing (Exception e): publicCall() {
	  System.out.println("Threw an exception: " + e);
      }
      after(): publicCall(){
	  System.out.println("Returned or threw an Exception");
      }
  }
</programlisting>

    <para>
      After returning advice may not care about its returned object, in which
      case it may be written
    </para>

<programlisting>
  after() returning: call(public Object *(..)) {
      System.out.println("Returned normally");
  }
</programlisting>

    <para>
      If after returning does expose its returned object, then the
      type of the parameter is considered to be an
      <literal>instanceof</literal>-like constraint on the advice:  it
      will run only when the return value is of the appropriate type.
    </para>

    <para>
      A value is of the appropriate type if it would be assignable to
      a variable of that type, in the Java sense.  That is, a
      <literal>byte</literal> value is assignable to a
      <literal>short</literal> parameter but not vice-versa, an
      <literal>int</literal> is assignable to a
      <literal>float</literal> parameter, <literal>boolean</literal>
      values are only assignable to <literal>boolean</literal>
      parameters, and reference types work by instanceof.
    </para>

    <para>
      There are two special cases: If the exposed value is typed to
      <literal>Object</literal>, then the advice is not constrained by
      that type: the actual return value is converted to an object
      type for the body of the advice: <literal>int</literal> values
      are represented as <literal>java.lang.Integer</literal> objects,
      etc, and no value (from void methods, for example) is
      represented as <literal>null</literal>.
    </para>

    <para>
      Secondly, the <literal>null</literal> value is assignable to a
      parameter <literal>T</literal> if the join point
      <emphasis>could</emphasis> return something of type
      <literal>T</literal>.
    </para>

    <para>
      Around advice runs in place of the join point it operates over, rather
      than before or after it.  Because around is allowed to return a value, it
      must be declared with a return type, like a method.
    </para>

    <para>
      Thus, a simple use of around advice is to make a particular method
      constant:
    </para>

<programlisting>
  aspect A {
      int around(): call(int C.foo()) {
	  return 3;
      }
  }
</programlisting>

    <para>
      Within the body of around advice, though, the computation of the original
      join point can be executed with the special syntax
    </para>

<programlisting>
  proceed( ... )
</programlisting>

    <para>
      The proceed form takes as arguments the context exposed by the around's
      pointcut, and returns whatever the around is declared to return. So the
      following around advice will double the second argument to
      <literal>foo</literal> whenever it is called, and then halve its result:
    </para>


<programlisting>
  aspect A {
      int around(int i): call(int C.foo(Object, int)) <![CDATA[&&]]> args(i) {
	  int newi = proceed(i*2)
	  return newi/2;
      }
  }
</programlisting>

    <para>
      If the return value of around advice is typed to
      <literal>Object</literal>, then the result of proceed is converted to an
      object representation, even if it is originally a primitive value.  And
      when the advice returns an Object value, that value is converted back to
      whatever representation it was originally.  So another way to write the
      doubling and halving advice is:
    </para>

<programlisting>
  aspect A {
      Object around(int i): call(int C.foo(Object, int)) <![CDATA[&&]]> args(i) {
	  Integer newi = (Integer) proceed(i*2)
	  return new Integer(newi.intValue() / 2);
      }
  }
</programlisting>

	<para>
		Any occurence of <literal>proceed(..)</literal> within the body of
		around advice is treated as the special proceed form (even if the
		aspect defines a method named <literal>proceed</literal>) unless a 
		target other than the aspect instance is specified as the recipient of
		the call.
		For example, in the following program the first 
		call to proceed will be treated as a method call to
		the <literal>ICanProceed</literal> instance, whereas the second call to
		proceed is treated as the special proceed form.
	</para>

<programlisting>
  aspect A {
     Object around(ICanProceed canProceed) : execution(* *(..)) <![CDATA[&&]]> this(canProceed) {
        canProceed.proceed();         // a method call
        return proceed(canProceed);   // the special proceed form
     }
     
     private Object proceed(ICanProceed canProceed) {
        // this method cannot be called from inside the body of around advice in
        // the aspect
     }
  }	
</programlisting>

    <para>
      In all kinds of advice, the parameters of the advice behave exactly like
      method parameters.  In particular, assigning to any parameter affects
      only the value of the parameter, not the value that it came from.  This
      means that
    </para>

<programlisting>
  aspect A {
      after() returning (int i): call(int C.foo()) {
	  i = i * 2;
      }
  }
</programlisting>

    <para>
      will <emphasis>not</emphasis> double the returned value of the advice.
      Rather, it will double the local parameter.  Changing the values of
      parameters or return values of join points can be done by using around
      advice.
    </para>

    <sect2>
      <title>Advice modifiers</title>

      <para>
        The <literal>strictfp</literal> modifier is the only modifier allowed
        on advice, and it has the effect of making all floating-point
        expressions within the advice be FP-strict.
      </para>
    </sect2>

    <sect2>
      <title>Advice and checked exceptions</title>

      <para>
        An advice declaration must include a <literal>throws</literal> clause
        listing the checked exceptions the body may throw.  This list of
        checked exceptions must be compatible with each target join point
        of the advice, or an error is signalled by the compiler.
      </para>

      <para>
        For example, in the following declarations:
      </para>

<programlisting>
  import java.io.FileNotFoundException;

  class C {
      int i;

      int getI() { return i; }
  }

  aspect A {
      before(): get(int C.i) {
	  throw new FileNotFoundException();
      }
      before() throws FileNotFoundException: get(int C.i) {
	  throw new FileNotFoundException();
      }
  }
</programlisting>

      <para>
        both pieces of advice are illegal.  The first because the body throws
        an undeclared checked exception, and the second because field get join
        points cannot throw <literal>FileNotFoundException</literal>s.
      </para>

      <para> The exceptions that each kind of join point in AspectJ may throw are:
      </para>

    <variablelist>
      <varlistentry>
        <term>method call and execution</term>
        <listitem>
          the checked exceptions declared by the target method's
          <literal>throws</literal> clause.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>constructor call and execution</term>
        <listitem>
          the checked exceptions declared by the target constructor's
          <literal>throws</literal> clause.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>field get and set</term>
        <listitem>
          no checked exceptions can be thrown from these join points. 
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>exception handler execution</term>
        <listitem>
          the exceptions that can be thrown by the target exception handler.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>static initializer execution</term>
        <listitem>
          no checked exceptions can be thrown from these join points. 
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>pre-initialization and initialization</term>
        <listitem>
          any exception that is in the throws clause of
          <emphasis>all</emphasis> constructors of the initialized class. 
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>advice execution</term>
        <listitem>
          any exception that is in the throws clause of the advice. 
        </listitem>
      </varlistentry>

    </variablelist>

    </sect2>

    <sect2>
      <title>Advice precedence</title>

      <para>
        Multiple pieces of advice may apply to the same join point.  In such
        cases, the resolution order of the advice is based on advice
        precedence.
      </para>

      <sect3>
        <title>Determining precedence</title>

        <para>There are a number of rules that determine whether a particular
        piece of advice has precedence over another when they advise the same
        join point. </para>

        <para>If the two pieces of advice are defined in different aspects,
        then there are three cases: </para>

        <itemizedlist>
          <listitem>If aspect A is matched earlier than aspect B in some
          <literal>declare precedence</literal> form, then all advice in
          concrete aspect A has precedence over all advice in concrete aspect B
          when they are on the same join point.  </listitem>

          <listitem>
          Otherwise, if aspect A is a subaspect of aspect B, then all advice
          defined in A has precedence over all advice defined in
          B. So, unless otherwise specified with
          <literal>declare precedence</literal>, advice in a subaspect
          has precedence over advice in a superaspect.
          </listitem>

          <listitem>
          Otherwise, if two pieces of advice are defined in two different
          aspects, it is undefined which one has precedence.
          </listitem>

        </itemizedlist>

        <para>If the two pieces of advice are defined in the same aspect, then
        there are two cases: </para>

        <itemizedlist>
          <listitem>If either are <literal>after</literal> advice, then the one that
          appears later in the aspect has precedence over the one that appears
          earlier. </listitem>

          <listitem>Otherwise, then the one that appears earlier in the aspect
          has precedence over the one that appears later.
          </listitem>

        </itemizedlist>

        <para>These rules can lead to circularity, such as</para>

<programlisting>
  aspect A {
      before(): execution(void main(String[] args)) {}
      after():  execution(void main(String[] args)) {}
      before(): execution(void main(String[] args)) {}
  }
</programlisting>

        <para>such circularities will result in errors signalled by the compiler. </para>
      </sect3>

      <sect3>
        <title>Effects of precedence</title>

        <para>At a particular join point, advice is ordered by precedence.</para>

        <para>A piece of <literal>around</literal> advice controls whether
        advice of lower precedence will run by calling
        <literal>proceed</literal>.  The call to <literal>proceed</literal>
        will run the advice with next precedence, or the computation under the
        join point if there is no further advice. </para>

        <para>A piece of <literal>before</literal> advice can prevent advice of
        lower precedence from running by throwing an exception.  If it returns
        normally, however, then the advice of the next precedence, or the
        computation under the join pint if there is no further advice, will run.
        </para>

        <para>Running <literal>after returning</literal> advice will run the
        advice of next precedence, or the computation under the join point if
        there is no further advice.  Then, if that computation returned
        normally, the body of the advice will run. </para>

        <para>Running <literal>after throwing</literal> advice will run the
        advice of next precedence, or the computation under the join
        point if there is no further advice.  Then, if that computation threw
        an exception of an appropriate type, the body of the advice will
        run. </para>

        <para>Running <literal>after</literal> advice will run the advice of
        next precedence, or the computation under the join point if
        there is no further advice.  Then the body of the advice will
        run. </para>
      </sect3>
    </sect2>

    <sect2>
      <title>Reflective access to the join point</title>

      <para>
        Three special variables are visible within bodies of advice:
        <literal>thisJoinPoint</literal>,
        <literal>thisJoinPointStaticPart</literal>, and
        <literal>thisEnclosingJoinPointStaticPart</literal>. Each is bound to
        an object that encapsulates some of the context of the advice's current
        or enclosing join point.  These variables exist because some pointcuts
        may pick out very large collections of join points. For example, the
        pointcut
      </para>


<programlisting>
  pointcut publicCall(): call(public * *(..));
</programlisting>


      <para>
        picks out calls to many methods. Yet the body of advice over this
        pointcut may wish to have access to the method name or parameters of a
        particular join point.
      </para>

      <para>
        <literal>thisJoinPoint</literal> is bound to a complete join point
        object.

      </para>

      <para>
        <literal>thisJoinPointStaticPart</literal> is bound to a part of the
        join point object that includes less information, but for which no
        memory allocation is required on each execution of the advice.  It is
        equivalent to <literal>thisJoinPoint.getStaticPart()</literal>.
      </para>

      <para>
        <literal>thisEnclosingJoinPointStaticPart</literal> is bound to the
        static part of the join point enclosing the current join point.  Only
        the static part of this enclosing join point is available through this
        mechanism.
      </para>

      <para>
        Standard Java reflection uses objects from the
        <literal>java.lang.reflect</literal> hierarchy to build up its
        reflective objects.  Similarly, AspectJ join point objects have types
        in a type hierarchy.  The type of objects bound to
        <literal>thisJoinPoint</literal> is
        <literal>org.aspectj.lang.JoinPoint</literal>, while
        <literal>thisStaticJoinPoint</literal> is bound to objects of interface
        type <literal>org.aspectj.lang.JoinPoint.StaticPart</literal>.
      </para>
    </sect2>

  </sect1>

  <sect1 id="semantics-declare">
    <title>Static crosscutting</title>

    <para>
      Advice declarations change the behavior of classes they crosscut, but do
      not change their static type structure. For crosscutting concerns that do
      operate over the static structure of type hierarchies, AspectJ provides
      inter-type member declarations and other <literal>declare</literal> forms.
    </para>

    <sect2>
      <title>Inter-type member declarations</title>

        <para>
          AspectJ allows the declaration of members by aspects that are
          associated with other types.
        </para>

      <para>
        An inter-type method declaration looks like
      </para>

      <itemizedlist>
        <listitem><literal>
        [ <replaceable>Modifiers</replaceable> ]
        <replaceable>Type</replaceable> <replaceable>OnType</replaceable>
        .
        <replaceable>Id</replaceable>(<replaceable>Formals</replaceable>)
        [ <replaceable>ThrowsClause</replaceable> ]
        { <replaceable>Body</replaceable> }</literal></listitem>

        <listitem><literal>abstract
        [ <replaceable>Modifiers</replaceable> ]
        <replaceable>Type</replaceable> <replaceable>OnType</replaceable>
        .  <replaceable>Id</replaceable>(<replaceable>Formals</replaceable>)
        [ <replaceable>ThrowsClause</replaceable> ]
        ;
        </literal></listitem>
      </itemizedlist>

      <para>
        The effect of such a declaration is to make <replaceable>OnType</replaceable>
        support the new method.  Even if <replaceable>OnType</replaceable> is
        an interface.  Even if the method is neither public nor abstract.  So the
        following is legal AspectJ code:
      </para>

<programlisting>
  interface Iface {}

  aspect A {
      private void Iface.m() {
	  System.err.println("I'm a private method on an interface");
      }
      void worksOnI(Iface iface) {
	  // calling a private method on an interface
	  iface.m();
      }
  }
</programlisting>

      <para>
        An inter-type constructor declaration looks like
      </para>

      <itemizedlist>
        <listitem><literal>
        [ <replaceable>Modifiers</replaceable> ]
        <replaceable>OnType</replaceable> . new (
        <replaceable>Formals</replaceable> )
        [ <replaceable>ThrowsClause</replaceable> ]
        { <replaceable>Body</replaceable> }</literal></listitem>
      </itemizedlist>

      <para>
        The effect of such a declaration is to make
        <replaceable>OnType</replaceable> support the new constructor.  It is
        an error for <replaceable>OnType</replaceable> to be an interface.
      </para>

	  <para>
	    Inter-type declared constructors cannot be used to assign a
	    value to a final variable declared in <replaceable>OnType</replaceable>.
	    This limitation significantly increases the ability to both understand
	    and compile the <replaceable>OnType</replaceable> class and the
	    declaring aspect separately.
	  </para>

      <para>
        Note that in the Java language, classes that define no constructors
        have an implicit no-argument constructor that just calls
        <literal>super()</literal>.  This means that attempting to declare
        a no-argument inter-type constructor on such a class may result in
        a conflict, even though it <emphasis>looks</emphasis> like no
        constructor is defined.
      </para>

      <para>
        An inter-type field declaration looks like one of
      </para>

      <itemizedlist>
        <listitem><literal>
        [ <replaceable>Modifiers</replaceable> ]
        <replaceable>Type</replaceable>
        <replaceable>OnType</replaceable> . <replaceable>Id</replaceable>
        = <replaceable>Expression</replaceable>;</literal></listitem>

        <listitem><literal>
        [ <replaceable>Modifiers</replaceable> ]
        <replaceable>Type</replaceable>
        <replaceable>OnType</replaceable> . <replaceable>Id</replaceable>;</literal></listitem>
      </itemizedlist>

      <para>
        The effect of such a declaration is to make
        <replaceable>OnType</replaceable> support the new field. Even if
        <replaceable>OnType</replaceable> is an interface. Even if the field is
        neither public, nor static, nor final.
      </para>

      <para>
        The initializer, if any, of an inter-type field declaration runs
        before the class-local initializers defined in its target class.
      </para>

    </sect2>

      <para>
        Any occurrence of the identifier <literal>this</literal> in the body of
        an inter-type constructor or method declaration, or in the initializer
        of an inter-type field declaration, refers to the
        <replaceable>OnType</replaceable> object rather than to the aspect
        type; it is an error to access <literal>this</literal> in such a
        position from a <literal>static</literal> inter-type member
        declaration.
      </para>

    <sect2>
      <title>Access modifiers</title>

      <para>
        Inter-type member declarations may be public or private, or have
        default (package-protected) visibility.  AspectJ does not provide
        protected inter-type members.
      </para>

      <para>
        The access modifier applies in relation to the aspect, not in relation
        to the target type. So a private inter-type member is visible only from
        code that is defined within the declaring aspect. A default-visibility
        inter-type member is visible only from code that is defined within the
        declaring aspect's package.
      </para>

      <para>
        Note that a declaring a private inter-type method (which AspectJ
        supports) is very different from inserting a private method declaration
        into another class.  The former allows access only from the declaring
        aspect, while the latter would allow access only from the target type.
        Java serialization, for example, uses the presense of a private method
        <literal>void writeObject(ObjectOutputStream)</literal> for the
        implementation of <literal>java.io.Serializable</literal>.  A private
        inter-type declaration of that method would not fulfill this
        requirement, since it would be private to the aspect, not private to
        the target type.
      </para>

      <para>
        The access modifier of abstract inter-type methods has
        one constraint: It is illegal to declare an abstract
        non-public inter-type method on a public interface.  This
        is illegal because it would say that a public interface
        has a constraint that only non-public implementors must
        fulfill.  This would not be compatible with Java's type
        system.  
      </para>
    </sect2>

    <sect2>
      <title>Conflicts</title>

      <para>
        Inter-type declarations raise the possibility of conflicts among
        locally declared members and inter-type members.  For example, assuming
        <literal>otherPackage</literal> is not the package containing the
        aspect <classname>A</classname>, the code
      </para>

<programlisting>
  aspect A {
      private Registry otherPackage.onType.r;
      public void otherPackage.onType.register(Registry r) {
	    r.register(this);
	    this.r = r;
      }
  }
</programlisting>

      <para>
        declares that <literal>onType</literal> in <literal>otherPackage</literal> has a field
        <literal>r</literal>.  This field, however, is only accessible from the
        code inside of aspect <literal>A</literal>.  The aspect also declares
        that <literal>onType</literal> has a method
        "<literal>register</literal>", but makes this method accessible from
        everywhere.
      </para>

      <para>
        If <literal>onType</literal> already defines a
        private or package-protected field "<literal>r</literal>", there is no
        conflict: The aspect cannot see such a field, and no code in
        <literal>otherPackage</literal> can see the inter-type
        "<literal>r</literal>".
      </para>

      <para>
        If <literal>onType</literal> defines a public field
        "<literal>r</literal>", there is a conflict: The expression
      </para>

<programlisting>
  this.r = r
</programlisting>

      <para>
        is an error, since it is ambiguous whether the private inter-type
        "<literal>r</literal>" or the public locally-defined
        "<literal>r</literal>" should be used.
      </para>

      <para>
        If <literal>onType</literal> defines a method
        "<literal>register(Registry)</literal>" there is a conflict, since it
        would be ambiguous to any code that could see such a defined method
        which "<literal>register(Registry)</literal>" method was applicable.
      </para>

      <para>
        Conflicts are resolved as much as possible as per Java's conflict
        resolution rules:
      </para>

      <itemizedlist>
        <listitem>A subclass can inherit multiple <emphasis>fields</emphasis> from its superclasses,
        all with the same name and type.  However, it is an error to have an ambiguous
        <emphasis>reference</emphasis> to a field.</listitem>

        <listitem>A subclass can only inherit multiple
        <emphasis>methods</emphasis> with the same name and argument types from
        its superclasses if only zero or one of them is concrete (i.e., all but
        one is abstract, or all are abstract).
        </listitem>
      </itemizedlist>

      <para>
        Given a potential conflict between inter-type member declarations in
        different aspects, if one aspect has precedence over the other its
        declaration will take effect without any conflict notice from compiler.
        This is true both when the precedence is declared explicitly with
        <literal>declare precedence</literal> as well as when when sub-aspects
        implicitly have precedence over their super-aspect.
      </para>

    </sect2>

    <sect2>
      <title>Extension and Implementation</title>

      <para>
        An aspect may change the inheritance hierarchy of a system by changing
        the superclass of a type or adding a superinterface onto a type, with
        the <literal>declare parents</literal> form.
      </para>

      <itemizedlist>
        <listitem><literal>declare parents: <replaceable>TypePattern</replaceable> extends <replaceable>Type</replaceable>;</literal></listitem>
        <listitem><literal>declare parents: <replaceable>TypePattern</replaceable> implements <replaceable>TypeList</replaceable>;</literal></listitem>
      </itemizedlist>

      <para>
        For example, if an aspect wished to make a particular class runnable,
        it might define appropriate inter-type <literal>void
        run()</literal> method, but it should also declare that the class
        fulfills the <literal>Runnable</literal> interface.  In order to
        implement the methods in the <literal>Runnable</literal> interface, the
        inter-type <literal>run()</literal> method must be public:
      </para>

<programlisting>
  aspect A {
      declare parents: SomeClass implements Runnable;
      public void SomeClass.run() { ... }
  }
</programlisting>

    </sect2>

    <sect2>
      <title>Interfaces with members</title>

      <para>
        Through the use of inter-type members, interfaces may now carry
        (non-public-static-final) fields and (non-public-abstract) methods that
        classes can inherit. Conflicts may occur from ambiguously inheriting
        members from a superclass and multiple superinterfaces.
      </para>

      <para>
        Because interfaces may carry non-static initializers, each interface
        behaves as if it has a zero-argument constructor containing its
        initializers.  The order of super-interface instantiation is
        observable. We fix this order with the following properties: A
        supertype is initialized before a subtype, initialized code runs only
        once, and the initializers for a type's superclass are run before the
        initializers for its superinterfaces.  Consider the following hierarchy
        where {<literal>Object</literal>, <literal>C</literal>,
        <literal>D</literal>, <literal>E</literal>} are classes,
        {<literal>M</literal>, <literal>N</literal>, <literal>O</literal>,
        <literal>P</literal>, <literal>Q</literal>} are interfaces.
      </para>

<programlisting>
    Object  M   O
	 \ / \ /
	  C   N   Q
	   \ /   /
	    D   P
	     \ /
	      E
</programlisting>

      <para>
        when a new <literal>E</literal> is instantiated, the initializers run in this order:
      </para>

<programlisting>
    Object M C O N D Q P E
</programlisting>

    </sect2>

<!-- ============================== -->

    <sect2>
      <title>Warnings and Errors</title>

      <para>An aspect may specify that a particular join point should never be
      reached.  </para>

      <itemizedlist>
        <listitem><literal>declare error: <replaceable>Pointcut</replaceable>: <replaceable>String</replaceable>;</literal></listitem>
        <listitem><literal>declare warning: <replaceable>Pointcut</replaceable>: <replaceable>String</replaceable>;</literal></listitem>
      </itemizedlist>

      <para>If the compiler determines that a join point in
      <replaceable>Pointcut</replaceable> could possibly be reached, then it
      will signal either an error or warning, as declared, using the
      <replaceable>String</replaceable> for its message.   </para>

    </sect2>

    <sect2>
      <title>Softened exceptions</title>

      <para>An aspect may specify that a particular kind of exception, if
      thrown at a join point, should bypass Java's usual static exception
      checking system and instead be thrown as a
      <literal>org.aspectj.lang.SoftException</literal>, which is subtype of
      <literal>RuntimeException</literal> and thus does not need to be
      declared.  </para>

      <itemizedlist>
        <listitem><literal>declare soft: <replaceable>Type</replaceable>: <replaceable>Pointcut</replaceable>;</literal></listitem>
      </itemizedlist>

      <para>For example, the aspect</para>

<programlisting>
  aspect A {
      declare soft: Exception: execution(void main(String[] args));
  }
</programlisting>

      <para>Would, at the execution join point, catch any
      <literal>Exception</literal> and rethrow a
      <literal>org.aspectj.lang.SoftException</literal> containing
      original exception. </para>

      <para>This is similar to what the following advice would do</para>

<programlisting>
  aspect A {
      void around() execution(void main(String[] args)) {
	  try { proceed(); }
	  catch (Exception e) {
	      throw new org.aspectj.lang.SoftException(e);
	  }
      }
  }
</programlisting>

      <para>except, in addition to wrapping the exception, it also affects
      Java's static exception checking mechanism. </para>

      <para> Like advice, the declare soft form has no effect in an
      abstract aspect that is not extended by a concreate aspect.  So
      the following code will not compile unless it is compiled with an
      extending concrete aspect:</para>

<programlisting>
  abstract aspect A {
    abstract pointcut softeningPC();

    before() : softeningPC() {     
      Class.forName("FooClass"); // error:  uncaught ClassNotFoundException
    }    
                                                      
    declare soft : ClassNotFoundException : call(* Class.*(..));
  }
</programlisting>

    </sect2>

    <sect2>
      <title>Advice Precedence</title>

      <para>
        An aspect may declare a precedence relationship between concrete
        aspects with the <literal>declare precedence</literal> form:
      </para>

      <itemizedlist>
        <listitem><literal>declare precedence :
        <replaceable>TypePatternList</replaceable> ; </literal></listitem>
      </itemizedlist>

      <para>This signifies that if any join point has advice from two
      concrete aspects matched by some pattern in
      <replaceable>TypePatternList</replaceable>, then the precedence of
      the advice will be the order of in the list.  </para>

      <para>In <replaceable>TypePatternList</replaceable>, the wildcard "*" can
      appear at most once, and it means "any type not matched by any other
      pattern in the list". </para>

      <para>For example, the constraints that (1) aspects that have
      Security as part of their name should have precedence over all other
      aspects, and (2) the Logging aspect (and any aspect that extends it)
      should have precedence over all non-security aspects, can be
      expressed by:</para>

<programlisting>
  declare precedence: *..*Security*, Logging+, *;
</programlisting>

      <para>
        For another example, the CountEntry aspect might want to count the
        entry to methods in the current package accepting a Type object as
        its first argument.  However, it should count all entries, even
        those that the aspect DisallowNulls causes to throw exceptions.
        This can be accomplished by stating that CountEntry has precedence
        over DisallowNulls.  This declaration could be in either aspect, or
        in another, ordering aspect:
      </para>

<programlisting>
  aspect Ordering {
      declare precedence: CountEntry, DisallowNulls;
  }
  aspect DisallowNulls {
      pointcut allTypeMethods(Type obj): call(* *(..)) <![CDATA[&&]]> args(obj, ..);
      before(Type obj):  allTypeMethods(obj) {
	  if (obj == null) throw new RuntimeException();
      }
  }
  aspect CountEntry {
      pointcut allTypeMethods(Type obj): call(* *(..)) <![CDATA[&&]]> args(obj, ..);
      static int count = 0;
      before():  allTypeMethods(Type) {
	  count++;
      }
  }
</programlisting>

      <sect3>
        <title>Various cycles</title>

        <para>
          It is an error for any aspect to be matched by more than one
          TypePattern in a single decare precedence, so:
        </para>

<programlisting>
  declare precedence:  A, B, A ;  // error
</programlisting>

        <para>
          However, multiple declare precedence forms may legally have this
          kind of circularity. For example, each of these declare
          precedence is perfectly legal:
        </para>

<programlisting>
  declare precedence: B, A;
  declare precedence: A, B;
</programlisting>

        <para>
          And a system in which both constraints are active may also be
          legal, so long as advice from A and B don't share a join
          point. So this is an idiom that can be used to enforce that A and
          B are strongly independent.
        </para>
      </sect3>

      <sect3>
        <title>Applies to concrete aspects</title>

        <para>
          Consider the following library aspects:
        </para>

<programlisting>
  abstract aspect Logging {
      abstract pointcut logged();

      before(): logged() {
          System.err.println("thisJoinPoint: " + thisJoinPoint);
      }
  }

  abstract aspect MyProfiling {
      abstract pointcut profiled();

      Object around(): profiled() {
          long beforeTime = System.currentTimeMillis();
          try {
              return proceed();
          } finally {
              long afterTime = System.currentTimeMillis();
              addToProfile(thisJoinPointStaticPart,
                           afterTime - beforeTime);
          }
      }
      abstract void addToProfile(
          org.aspectj.JoinPoint.StaticPart jp,
          long elapsed);
  }
</programlisting>

        <para>
          In order to use either aspect, they must be extended with
          concrete aspects, say, MyLogging and MyProfiling. Because advice
          only applies from concrete aspects, the declare precedence form
          only matters when declaring precedence with concrete aspects.  So
        </para>

<programlisting>
  declare precedence: Logging, Profiling;
</programlisting>

        <para>
          has no effect, but both
        </para>

<programlisting>
  declare precedence: MyLogging, MyProfiling;
  declare precedence: Logging+, Profiling+;
</programlisting>

        <para>
          are meaningful.
        </para>
      </sect3>
    </sect2>


    <sect2>
      <title>Statically determinable pointcuts</title>

      <para>Pointcuts that appear inside of <literal>declare</literal> forms
      have certain restrictions.  Like other pointcuts, these pick out join
      points, but they do so in a way that is statically determinable.  </para>

      <para>Consequently, such pointcuts may not include, directly or
      indirectly (through user-defined pointcut declarations) pointcuts that
      discriminate based on dynamic (runtime) context.  Therefore, such
      pointcuts may not be defined in terms of</para>

      <itemizedlist>
        <listitem>cflow</listitem>
        <listitem>cflowbelow</listitem>
        <listitem>this</listitem>
        <listitem>target</listitem>
        <listitem>args</listitem>
        <listitem>if</listitem>
      </itemizedlist>

      <para> all of which can discriminate on runtime information. </para>
    </sect2>
  </sect1>

  <sect1 id="semantics-aspects">
    <title>Aspects</title>

    <para>
      An aspect is a crosscutting type defined by the <literal>aspect</literal>
      declaration. 
    </para>

    <sect2>
      <title>Aspect Declaration</title>

      <para>
        The <literal>aspect</literal> declaration is similar to the
	<literal>class</literal> declaration in that it defines a type and an
	implementation for that type. It differs in a number of
	ways:
      </para>

      <sect3>
        <title>Aspect implementation can cut across other types</title>

	<para> In addition to normal Java class declarations such as
	methods and fields, aspect declarations can include AspectJ
	declarations such as advice, pointcuts, and inter-type
	declarations.  Thus, aspects contain implementation
	declarations that can can cut across other types (including those defined by
	other aspect declarations).
        </para>
      </sect3> 

      <sect3>
        <title>Aspects are not directly instantiated</title>

	<para> Aspects are not directly instantiated with a new
	expression, with cloning, or with serialization. Aspects may
	have one constructor definition, but if so it must be of a
	constructor taking no arguments and throwing no checked
	exceptions.
        </para>
      </sect3> 

      <sect3>
        <title>Nested aspects must be <literal>static</literal></title>

	<para> 
	  Aspects may be defined either at the package level, or as a static nested
          aspect -- that is, a static member of a class, interface, or aspect.  If it
          is not at the package level, the aspect <emphasis>must</emphasis> be
          defined with the static keyword.  Local and anonymous aspects are not
          allowed.
        </para>
      </sect3> 
    </sect2>

    <sect2>
      <title>Aspect Extension</title>

      <para>
        To support abstraction and composition of crosscutting concerns,
        aspects can be extended in much the same way that classes can. Aspect
        extension adds some new rules, though.
      </para>

      <sect3>
        <title>Aspects may extend classes and implement interfaces</title>

        <para>
          An aspect, abstract or concrete, may extend a class and may implement
          a set of interfaces. Extending a class does not provide the ability
          to instantiate the aspect with a new expression: The aspect may still
          only define a null constructor.
        </para>
      </sect3>

      <sect3>
        <title>Classes may not extend aspects</title>

        <para>
          It is an error for a class to extend or implement an aspect.
        </para>
      </sect3>

      <sect3>
        <title>Aspects extending aspects
        </title>
        <para>
          Aspects may extend other aspects, in which case not only are fields
          and methods inherited but so are pointcuts. However, aspects may only
          extend abstract aspects. It is an error for a concrete aspect to
          extend another concrete aspect.
        </para>
      </sect3>
    </sect2>

    <sect2>
      <title>Aspect instantiation</title>

      <para>
        Unlike class expressions, aspects are not instantiated with
        <literal>new</literal> expressions.  Rather, aspect instances are
        automatically created to cut across programs.
      </para>

      <para>
        Because advice only runs in the context of an aspect instance, aspect
        instantiation indirectly controls when advice runs.
      </para>

      <para>
        The criteria used to determine how an aspect is instantiated
        is inherited from its parent aspect.  If the aspect has no parent
        aspect, then by default the aspect is a singleton aspect.
      </para>

      <sect3>
        <title>Singleton Aspects</title>

        <itemizedlist>
          <listitem><literal>aspect <replaceable>Id</replaceable> { ... }</literal></listitem>
          <listitem><literal>aspect <replaceable>Id</replaceable> issingleton() { ... }</literal></listitem>
        </itemizedlist>

        <para>
          By default (or by using the modifier <literal>issingleton()</literal>)
          an aspect has exactly one instance that cuts across the entire
          program.  That instance is available at any time during program
          execution with the static method <literal>aspectOf()</literal>
          defined on the aspect
          -- so, in the above examples, <literal>A.aspectOf()</literal> will
          return A's instance.  This aspect instance is created as the aspect's
          classfile is loaded.
        </para>

        <para>
          Because the an instance of the aspect exists at all join points in
          the running of a program (once its class is loaded), its advice will
          have a chance to run at all such join points.
        </para>

        <para>
          (In actuality, one instance of the aspect A is made for each version
          of the aspect A, so there will be one instantiation for each time A
          is loaded by a different classloader.)
        </para>
      </sect3>

      <sect3>
        <title>Per-object aspects</title>

        <itemizedlist>
          <listitem><literal>aspect <replaceable>Id</replaceable> perthis(<replaceable>Pointcut</replaceable>) { ... }</literal></listitem>
          <listitem><literal>aspect <replaceable>Id</replaceable> pertarget(<replaceable>Pointcut</replaceable>) { ... }</literal></listitem>
        </itemizedlist>

        <para>
          If an aspect A is defined
          <literal>perthis(<replaceable>Pointcut</replaceable>)</literal>, then
          one object of type A is created for every object that is the
          executing object (i.e., "this") at any of the join points picked out
          by <replaceable>Pointcut</replaceable>.
          The advice defined in A will run only at a join point where the
          currently executing object has been associated with an instance of
          A.
        </para>

        <para> Similarly, if an aspect A is defined
          <literal>pertarget(<replaceable>Pointcut</replaceable>)</literal>,
          then one object of type A is created for every object that is the
          target object of the join points picked out by
          <replaceable>Pointcut</replaceable>.
          The advice defined in A will run only at a join point where the
          target object has been associated with an instance of 
		  A.
        </para>

        <para>
          In either case, the static method call
          <literal>A.aspectOf(Object)</literal> can be used to get the aspect
          instance (of type A) registered with the object.  Each aspect
          instance is created as early as possible, but not before reaching a
          join point picked out by <replaceable>Pointcut</replaceable> where
          there is no associated aspect of type A.
        </para>

        <para> Both <literal>perthis</literal> and <literal>pertarget</literal>
        aspects may be affected by code the AspectJ compiler controls, as
        discussed in the <xref linkend="implementation"/> appendix.  </para>
      </sect3>

      <sect3>
        <title>Per-control-flow aspects</title>

        <itemizedlist>
          <listitem><literal>aspect <replaceable>Id</replaceable> percflow(<replaceable>Pointcut</replaceable>) { ... }</literal></listitem>
          <listitem><literal>aspect <replaceable>Id</replaceable> percflowbelow(<replaceable>Pointcut</replaceable>) { ... }</literal></listitem>
        </itemizedlist>

        <para>
          If an aspect A is defined
          <literal>percflow(<replaceable>Pointcut</replaceable>)</literal> or
          <literal>percflowbelow(<replaceable>Pointcut</replaceable>)</literal>,
          then one object of type A is created for each flow of control of the
          join points picked out by <replaceable>Pointcut</replaceable>, either
          as the flow of control is entered, or below the flow of control,
          respectively.  The advice defined in A may run at any join point in
          or under that control flow.  During each such flow of control, the
          static method <literal>A.aspectOf()</literal> will return an object
          of type
          A. An instance of the aspect is created upon entry into each such
          control flow.
        </para>
      </sect3>

      <sect3>
        <title>Aspect instantiation and advice</title>

        <para>
          All advice runs in the context of an aspect instance,
          but it is possible to write a piece of advice with a pointcut
          that picks out a join point that must occur before asopect
          instantiation.  For example:
        </para>

<programlisting>
  public class Client
  {
      public static void main(String[] args) {
          Client c = new Client();
      }
  }

  aspect Watchcall {
      pointcut myConstructor(): execution(new(..));

      before(): myConstructor() {
          System.err.println("Entering Constructor");
      }
  }
</programlisting>

        <para>
          The before advice should run before the execution of all
          constructors in the system. It must run in the context of an
          instance of the Watchcall aspect. The only way to get such an
          instance is to have Watchcall's default constructor execute. But
          before that executes, we need to run the before advice...
        </para>

        <para>
          There is no general way to detect these kinds of circularities at
          compile time.  If advice runs before its aspect is instantiated,
          AspectJ will throw a <ulink
          url="../api/org/aspectj/lang/NoAspectBoundException.html">
          <literal>org.aspectj.lang.NoAspectBoundException</literal></ulink>.
        </para>
      </sect3>
    </sect2>

    <sect2>
      <title>Aspect privilege</title>

      <itemizedlist>
        <listitem><literal>privileged aspect <replaceable>Id</replaceable> { ... }</literal></listitem>
      </itemizedlist>

      <para>
        Code written in aspects is subject to the same access control rules as
        Java code when referring to members of classes or aspects. So, for
        example, code written in an aspect may not refer to members with
        default (package-protected) visibility unless the aspect is defined in
        the same package.
      </para>

      <para>
        While these restrictions are suitable for many aspects, there may be
        some aspects in which advice or inter-type members needs to access private
        or protected resources of other types. To allow this, aspects may be
        declared <literal>privileged</literal>.  Code in priviliged aspects has
        access to all members, even private ones.
      </para>

<programlisting>
  class C {
      private int i = 0;
      void incI(int x) { i = i+x; }
  }
  privileged aspect A {
      static final int MAX = 1000;
      before(int x, C c): call(void C.incI(int)) <![CDATA[&&]]> target(c) <![CDATA[&&]]> args(x) {
	  if (c.i+x &gt; MAX) throw new RuntimeException();
      }
  }
</programlisting>

      <para>
        In this case, if A had not been declared privileged, the field reference
        c.i would have resulted in an error signaled by the compiler.
      </para>

      <para>
        If a privileged aspect can access multiple versions of a particular
        member, then those that it could see if it were not privileged take
        precedence. For example, in the code
      </para>

<programlisting>
  class C {
      private int i = 0;
      void foo() { }
  }
  privileged aspect A {
      private int C.i = 999;
      before(C c): call(void C.foo()) target(c) {
	  System.out.println(c.i);
      }
  }
</programlisting>

      <para>
        A's private inter-type field C.i, initially bound to 999, will be
        referenced in the body of the advice in preference to C's privately
        declared field, since the A would have access to its own inter-type
        fields even if it were not privileged.
      </para>

      <para>
        Note that a privileged aspect can access private inter-type
        declarations made by other aspects, since they are simply
        considered private members of that other aspect.
      </para>
    </sect2>
  </sect1>
</appendix>