path: root/docs/progGuideDB/quickreference.xml

<appendix id="quick" xreflabel="AspectJ Quick Reference">
  <title>AspectJ Quick Reference</title>

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

    <informaltable frame="none">
      <tgroup cols="2" align="left">
        <colspec colname="c1"/>
        <colspec colname="c2"/>

        <tbody valign="top">
          <row>
            <entry namest="c1" nameend="c2">
              <emphasis role="bold">Methods and Constructors</emphasis>
            </entry>
          </row>

          <row>
            <entry>
              <literal>call(<replaceable>Signature</replaceable>)</literal>
            </entry>

            <entry>
              every call to any method or constructor matching
              <replaceable>Signature</replaceable> at the call site
            </entry>
          </row>

          <row>
            <entry>
              <literal>execution(<replaceable>Signature</replaceable>)</literal>
            </entry>

            <entry>
              every execution of any method or constructor matching
              <replaceable>Signature</replaceable>
            </entry>
          </row>


          <!-- ===== -->
          <row>
            <entry namest="c1" nameend="c2">
              <emphasis role="bold">Fields</emphasis>
            </entry>
          </row>

          <row>
            <entry>
              <literal>get(<replaceable>Signature</replaceable>)</literal>
            </entry>
            <entry>
              every reference to any field matching <replaceable>Signature</replaceable>
            </entry>
          </row>

          <row>
            <entry>
              <literal>set(<replaceable>Signature</replaceable>)</literal>
            </entry>
            <entry>
              every assignment to any field matching
              <replaceable>Signature</replaceable>. The assigned value can
              be exposed with an <literal>args</literal> pointcut
            </entry>
          </row>

          <!-- ===== -->
          <row>
            <entry namest="c1" nameend="c2">
              <emphasis role="bold">Exception Handlers</emphasis>
            </entry>
          </row>

          <row rowsep="1">
            <entry>
              <literal>handler(<replaceable>TypePattern</replaceable>)</literal>
            </entry>
            <entry>
              every exception handler for any <literal>Throwable</literal>
              type in <replaceable>TypePattern</replaceable>. The exception
              value can be exposed with an <literal>args</literal> pointcut
            </entry>
          </row>

          <!-- ===== -->
          <row>
            <entry namest="c1" nameend="c2">
              <emphasis role="bold">Advice</emphasis>
            </entry>
          </row>

          <row>
            <entry>
              <literal>adviceexecution()</literal>
            </entry>
            <entry>
              every execution of any piece of advice
            </entry>
          </row>

          <!-- ===== -->
          <row>
            <entry namest="c1" nameend="c2">
              <emphasis role="bold">Initialization</emphasis>
            </entry>
          </row>

          <row rowsep="1">
            <entry>
              <literal>staticinitialization(<replaceable>TypePattern</replaceable>)</literal>
            </entry>
            <entry>
              every execution of a static initializer for any type in
              <replaceable>TypePattern</replaceable>
            </entry>
          </row>

          <row>
            <entry>
              <literal>initialization(<replaceable>Signature</replaceable>)</literal>
            </entry>
            <entry>
              every initialization of an object when the first constructor
              called in the type matches
              <replaceable>Signature</replaceable>, encompassing the return
              from the super constructor call to the return of the
              first-called constructor
            </entry>
          </row>
          <row>
            <entry>
              <literal>preinitialization(<replaceable>Signature</replaceable>)</literal>
            </entry>
            <entry>
              every pre-initialization of an object when the first
              constructor called in the type matches
              <replaceable>Signature</replaceable>, encompassing the entry
              of the first-called constructor to the call to the super
              constructor
            </entry>
          </row>

          <!-- ===== -->
          <row>
            <entry namest="c1" nameend="c2">
              <emphasis role="bold">Lexical</emphasis>
            </entry>
          </row>

          <row>
            <entry>
              <literal>within(<replaceable>TypePattern</replaceable>)</literal>
            </entry>
            <entry>
              every join point from code defined in a type in
              <replaceable>TypePattern</replaceable>
            </entry>
          </row>

          <row>
            <entry>
              <literal>withincode(<replaceable>Signature</replaceable>)</literal>
            </entry>
            <entry>
              every join point from code defined in a method or constructor
              matching <replaceable>Signature</replaceable>
            </entry>
          </row>
        </tbody>
      </tgroup>

      <tgroup cols="2" align="left">
        <colspec colname="c1"/>
        <colspec colname="c2"/>
        <tbody valign="top">
          <row>
            <entry namest="c1" nameend="c2" >
              <emphasis role="bold">Instanceof checks and context exposure</emphasis>
            </entry>
          </row>

          <row>
            <entry>
              <literal>this(<replaceable>Type</replaceable> or <replaceable>Id</replaceable>)</literal>
            </entry>
            <entry>
              every join point when the currently executing object is an
              instance of <replaceable>Type</replaceable> or
              <replaceable>Id</replaceable>'s type
            </entry>
          </row>

          <row>
            <entry>
              <literal>target(<replaceable>Type</replaceable> or <replaceable>Id</replaceable>)</literal>
            </entry>
            <entry>
              every join point when the target executing object is an
              instance of <replaceable>Type</replaceable> or
              <replaceable>Id</replaceable>'s type
            </entry>
          </row>

          <row>
            <entry>
              <literal>args(<replaceable>Type</replaceable> or
              <replaceable>Id</replaceable>, ...)</literal>
            </entry>
            <entry>
              every join point when the arguments are instances of
              <replaceable>Type</replaceable>s or the types of the
              <replaceable>Id</replaceable>s
            </entry>
          </row>

          <!-- ===== -->
          <row>
            <entry namest="c1" nameend="c2">
              <emphasis role="bold">Control Flow</emphasis>
            </entry>
          </row>

          <row>
            <entry>
              <literal>cflow(<replaceable>Pointcut</replaceable>)</literal>
            </entry>
            <entry>
              every join point in the control flow of each join point
              <replaceable>P</replaceable> picked out by
              <replaceable>Pointcut</replaceable>, including
              <replaceable>P</replaceable> itself
            </entry>
          </row>

          <row>
            <entry>
              <literal>cflowbelow(<replaceable>Pointcut</replaceable>)</literal>
            </entry>
            <entry>
              every join point below the control flow of each join point
              <replaceable>P</replaceable> picked out by
              <replaceable>Pointcut</replaceable>; does not include
              <replaceable>P</replaceable> itself
            </entry>
          </row>

          <!-- ===== -->
          <row>
            <entry namest="c1" nameend="c2">
              <emphasis role="bold">Conditional</emphasis>
            </entry>
          </row>

          <row>
            <entry>
              <literal>if(<replaceable>Expression</replaceable>)</literal>
            </entry>
            <entry>
              every join point when the boolean
              <replaceable>Expression</replaceable> is
              <literal>true</literal>
            </entry>
          </row>
        </tbody>
      </tgroup>

      <tgroup cols="2" align="left">
        <colspec colname="c1"/>
        <colspec colname="c2"/>

        <tbody valign="top">
          <row>
            <entry namest="c1" nameend="c2">
              <emphasis role="bold">Combination</emphasis>
            </entry>
          </row>

          <row>
            <entry>
              <literal>! <replaceable>Pointcut</replaceable></literal>
            </entry>
            <entry>
              every join point not picked out by
              <replaceable>Pointcut</replaceable>
            </entry>
          </row>

          <row>
            <entry>
              <literal><replaceable>Pointcut0</replaceable> <![CDATA[&&]]> <replaceable>Pointcut1</replaceable></literal>
            </entry>
            <entry>
              each join point picked out by both
              <replaceable>Pointcut0</replaceable> and
              <replaceable>Pointcut1</replaceable>
            </entry>
          </row>

          <row>
            <entry>
              <literal><replaceable>Pointcut0</replaceable> || <replaceable>Pointcut1</replaceable></literal>
            </entry>
            <entry>
              each join point picked out by either
              <replaceable>Pointcut0</replaceable> or
              <replaceable>Pointcut1</replaceable>
            </entry>
          </row>

          <row>
            <entry>
              <literal>( <replaceable>Pointcut</replaceable> )</literal>
            </entry>
            <entry>
              each join point picked out by
              <replaceable>Pointcut</replaceable>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </sect1>

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

  <sect1 id="quick-typePatterns">
    <title>Type Patterns</title>

    <para>
      A type pattern is one of
    </para>

    <informaltable frame="none">
      <tgroup cols="2" >
        <tbody valign="top">
          <row>
            <entry><replaceable>TypeNamePattern</replaceable></entry>
            <entry>all types in <replaceable>TypeNamePattern</replaceable></entry>
          </row>
          <row>
            <entry><replaceable>SubtypePattern</replaceable></entry>
            <entry>all types in <replaceable>SubtypePattern</replaceable>, a
            pattern with a +. </entry>
          </row>
          <row>
            <entry><replaceable>ArrayTypePattern</replaceable></entry>
            <entry>all types in <replaceable>ArrayTypePattern</replaceable>,
            a pattern with one or more []s. </entry>
          </row>
          <row>
            <entry><literal>!<replaceable>TypePattern</replaceable></literal></entry>
            <entry>all types not in <replaceable>TypePattern</replaceable></entry>
          </row>
          <row>
            <entry><literal><replaceable>TypePattern0</replaceable>
            <![CDATA[&&]]> <replaceable>TypePattern1</replaceable></literal></entry>
            <entry>all types in both
            <replaceable>TypePattern0</replaceable> and <replaceable>TypePattern1</replaceable></entry>
          </row>
          <row>
            <entry><literal><replaceable>TypePattern0</replaceable> || <replaceable>TypePattern1</replaceable></literal></entry>
            <entry>all types in either
            <replaceable>TypePattern0</replaceable> or <replaceable>TypePattern1</replaceable></entry>
          </row>
          <row>
            <entry><literal>( <replaceable>TypePattern</replaceable> )</literal></entry>
            <entry>all types in <replaceable>TypePattern</replaceable></entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>

    <para>
      where <replaceable>TypeNamePattern</replaceable> can either be a
      plain type name, the wildcard <literal>*</literal> (indicating all
      types), or an identifier with embedded <literal>*</literal> and
      <literal>..</literal> wildcards.
    </para>

    <para>
      An embedded <literal>*</literal> in an identifier matches any
      sequence of characters, but does not match the package (or
      inner-type) separator ".".
    </para>

    <para>
      An embedded <literal>..</literal> in an identifier matches any
      sequence of characters that starts and ends with the package (or
      inner-type) separator ".".
    </para>
  </sect1>

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

  <sect1 id="quick-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>

    <variablelist>
      <varlistentry>
        <term>
          <literal>before( <replaceable>Formals</replaceable> ) </literal>
        </term>
        <listitem>
          runs before each join point
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>after( <replaceable>Formals</replaceable> ) returning
          [ ( <replaceable>Formal</replaceable> ) ] </literal>
        </term>
        <listitem>
          runs after each join point that returns normally.  The
          optional formal gives access to the returned value
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>after( <replaceable>Formals</replaceable> ) throwing [
          ( <replaceable>Formal</replaceable> ) ] </literal>
        </term>
        <listitem>
          runs after each join point that throws a
          <literal>Throwable</literal>.  If the optional formal is
          present, runs only after each join point that throws a
          <literal>Throwable</literal> of the type of
          <replaceable>Formal</replaceable>, and
          <replaceable>Formal</replaceable> gives access to the
          <literal>Throwable</literal> exception value
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <literal>after( <replaceable>Formals</replaceable> ) </literal>
        </term>
        <listitem>
          runs after each join point regardless of whether it returns
          normally or throws a <literal>Throwable</literal>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal><replaceable>Type</replaceable>
          around( <replaceable>Formals</replaceable> ) </literal>
        </term>
        <listitem>
          runs in place of each join point. The join point can be
          executed by calling <literal>proceed</literal>, which takes
          the same number and types of arguments as the around advice.
        </listitem>
      </varlistentry>
    </variablelist>

    <para>
      Three special variables are available inside of advice bodies:
    </para>

    <variablelist>
      <varlistentry>
        <term>
          <literal>thisJoinPoint</literal>
        </term>
        <listitem>
          an object of type <ulink
      url="../api/org/aspectj/lang/JoinPoint.html"><literal>org.aspectj.lang.JoinPoint</literal></ulink>
      representing the join point at which the advice is executing.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>thisJoinPointStaticPart</literal>
        </term>
        <listitem>
          equivalent to <literal>thisJoinPoint.getStaticPart()</literal>,
          but may use fewer runtime resources.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>thisEnclosingJoinPointStaticPart</literal>
        </term>
        <listitem>
          the static part of the dynamically enclosing join point.
        </listitem>
      </varlistentry>
    </variablelist>
  </sect1>

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

  <sect1 id="quick-interType">
    <title>Inter-type member declarations</title>

    <para>
      Each inter-type member is one of
    </para>

    <variablelist>
      <varlistentry>
        <term>
          <literal>
            <replaceable>Modifiers ReturnType OnType . Id</replaceable>
            ( <replaceable>Formals</replaceable> )
            [ throws <replaceable>TypeList</replaceable> ]
            { <replaceable>Body</replaceable> }
          </literal>
        </term>
        <listitem>
          a method on <replaceable>OnType</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>
            abstract <replaceable>Modifiers ReturnType OnType . Id</replaceable>
            ( <replaceable>Formals</replaceable> )
            [ throws <replaceable>TypeList</replaceable> ] ;
          </literal>
        </term>
        <listitem>
          an abstract method on <replaceable>OnType</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>
            <replaceable>Modifiers OnType . </replaceable> new
            ( <replaceable>Formals</replaceable> )
            [ throws <replaceable>TypeList</replaceable> ]
            { <replaceable>Body</replaceable> }
          </literal>
        </term>
        <listitem>
          a constructor on <replaceable>OnType</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>
            <replaceable>Modifiers Type OnType . Id </replaceable>
            [ = <replaceable>Expression</replaceable> ] ;
          </literal>
        </term>
        <listitem>
          a field on <replaceable>OnType</replaceable>.
        </listitem>
      </varlistentry>
    </variablelist>
  </sect1>

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

  <sect1 id="quick-other">
    <title>Other declarations</title>

    <variablelist>
      <varlistentry>
        <term>
          <literal>
            declare parents :
            <replaceable>TypePattern</replaceable> extends
            <replaceable>Type</replaceable> ;
          </literal>
        </term>
        <listitem>
          the types in <replaceable>TypePattern</replaceable> extend
          <replaceable>Type</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>
            declare parents : <replaceable>TypePattern</replaceable>
            implements <replaceable>TypeList</replaceable> ;
          </literal>
        </term>
        <listitem>
          the types in <replaceable>TypePattern</replaceable>
          implement the types in <replaceable>TypeList</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>
            declare warning : <replaceable>Pointcut</replaceable> :
            <replaceable>String</replaceable> ;
          </literal>
        </term>
        <listitem>
          if any of the join points in <replaceable>Pointcut</replaceable>
          possibly exist in the program, the compiler emits the warning
          <replaceable>String</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>
            declare error : <replaceable>Pointcut</replaceable> :
            <replaceable>String</replaceable> ;
          </literal>
        </term>
        <listitem>
          if any of the join points in <replaceable>Pointcut</replaceable>
          could possibly exist in the program, the compiler emits the
          error <replaceable>String</replaceable>.
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <literal>
            declare soft :
            <replaceable>Type</replaceable> :
            <replaceable>Pointcut</replaceable> ;
          </literal>
        </term>
        <listitem>
          any <replaceable>Type</replaceable> exception
          that gets thrown at any join point picked out by
          <replaceable>Pointcut</replaceable> is wrapped in <ulink
          url="../api/org/aspectj/lang/SoftException.html"><literal>org.aspectj.lang.SoftException</literal></ulink>.
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <literal>
            declare precedence :
            <replaceable>TypePatternList</replaceable> ;
          </literal>
        </term>
        <listitem>
          at any join point where multiple pieces of advice
          apply, the advice precedence at that join point is in
          <replaceable>TypePatternList</replaceable> order.
        </listitem>
      </varlistentry>
    </variablelist>
  </sect1>

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

  <sect1 id="quick-aspectAssociations">
    <title>Aspects</title>

    <para>
      Each aspect is of the form

      <blockquote>
        <literal>
          [ privileged ] <replaceable>Modifiers</replaceable>
          aspect <replaceable>Id</replaceable>
          [ extends <replaceable>Type</replaceable> ]
          [ implements <replaceable>TypeList</replaceable> ]
          [ <replaceable>PerClause</replaceable> ]
          { <replaceable>Body</replaceable> }
        </literal>
      </blockquote>
    where <replaceable>PerClause</replaceable> defines how the aspect is
    instantiated and associated (<literal>issingleton()</literal> by
    default):
    </para>

    <informaltable frame="none">
      <tgroup cols="3" align="left">
        <thead>
          <row>
            <entry align="left">PerClause</entry>
            <entry align="left">Description</entry>
            <entry align="left">Accessor</entry>
          </row>
        </thead>

        <tbody valign="top">
          <row>
            <entry>
              [ <literal>issingleton()</literal> ]
            </entry>
            <entry>
              One instance of the aspect is made.  This is
              the default.
            </entry>
            <entry>
              <literal>aspectOf()</literal> at all join points
            </entry>
          </row>

          <row>
            <entry>
              <literal>perthis(<replaceable>Pointcut</replaceable>)</literal>
            </entry>
            <entry>
              An instance is associated with each object that is the
              currently executing object at any join point in
              <replaceable>Pointcut</replaceable>.
            </entry>
            <entry>
              <literal>aspectOf(Object)</literal> at all join points
            </entry>
          </row>

          <row>
            <entry>
              <literal>pertarget(<replaceable>Pointcut</replaceable>)</literal>
            </entry>
            <entry>
              An instance is associated with each object that is the
              target object at any join point in
              <replaceable>Pointcut</replaceable>.
            </entry>
            <entry>
              <literal>aspectOf(Object)</literal> at all join points
            </entry>
          </row>

          <row>
            <entry>
              <literal>percflow(<replaceable>Pointcut</replaceable>)</literal>
            </entry>
            <entry>
              The aspect is defined for each entrance to the control flow of
              the join points defined by <replaceable>Pointcut</replaceable>. </entry>
            <entry>
              <literal>aspectOf()</literal> at join points in
              <literal>cflow(<replaceable>Pointcut</replaceable>)</literal>
            </entry>
          </row>

          <row>
            <entry>
              <literal>percflowbelow(<replaceable>Pointcut</replaceable>)</literal>
            </entry>
            <entry>
              The aspect is defined for each entrance to the control flow
              below the join points defined by <replaceable>Pointcut</replaceable>.
            </entry>
            <entry>
              <literal>aspectOf()</literal> at join points in
              <literal>cflowbelow(<replaceable>Pointcut</replaceable>)</literal>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </sect1>

</appendix>