path: root/docs/adk15ProgGuideDB/joinpointsignatures.xml

<chapter id="jpsigs" xreflabel="Join Point Signatures">

  <title>Join Point Signatures</title>

    <para>
        Many of the extensions to the AspectJ language to address the new features of
        Java 5 are derived from a simple set of principles for join point
        matching. In this section, we outline these principles as a foundation
        for understanding the matching rules in the presence of annotations,
        generics, covariance, varargs, and autoboxing.
    </para>
  
    <sect1 id="join-point-matching">
        <title>Join Point Matching</title>
    
        <para>AspectJ supports 11 different kinds of join points. These are
        the <literal>method call, method execution, constructor call,
        constructor execution, field get, field set, pre-initialization,
        initialization, static initialization, handler,</literal> and
        <literal>advice execution</literal> join points.</para>
        
        <para>The <emphasis>kinded</emphasis> pointcut designators match
        based on the kind of a join point. These are the <literal>call,
        execution, get, set, preinitialization, initialization, 
        staticinitialization, handler,</literal> and <literal>adviceexecution</literal>
        designators.</para>
        
        <para>A kinded pointcut is written using patterns, some of which 
        match based on <emphasis>signature</emphasis>, and some of which
        match based on <emphasis>modifiers</emphasis>. For example, in 
        the <literal>call</literal> pointcut designator:</para>
        
        <programlisting><![CDATA[
        call(ModifierPattern TypePattern TypePattern.IdPattern(TypePatternList) ThrowsPattern)
		]]></programlisting>
		
		<para>the modifiers matching patterns are <literal>ModifierPattern</literal>
		and <literal>ThrowsPattern</literal>, and the signature matching patterns
		are <literal>TypePattern TypePattern.IdPattern(TypePatternList)</literal>.
		</para>
		
		<para>
		A join point has potentially multiple signatures, but only one set of
		modifiers. <emphasis>A kinded primitive pointcut matches a particular join point 
		if and only if</emphasis>:
		</para>
		
		<orderedlist>
		    <listitem>They are of the same kind</listitem>
		    <listitem>The signature pattern (exactly) matches at least one 
		    signature of the join point</listitem>
		    <listitem>The modifiers pattern matches the modifiers of the
		    subject of the join point</listitem>
		</orderedlist>
        
        <para>These rules make it very easily to quickly determine whether a 
        given pointcut matches a given join point. In the next two sections,
        we describe what the signature(s) of a join point are, and what the
        subjects of join points are.</para>
        
    </sect1>
  
      <sect1 id="join-point-signatures">
        <title>Join Point Signatures</title>
        
        <para>Call, execution, get, and set join points may potentially have multiple
        signatures. All other join points have exactly one signature. The
        following table summarizes the constituent parts of a join point
        signature for the different kinds of join point.</para>
        
        <informaltable>
        <tgroup cols="7">
            <thead>
                <row>
                    <entry>Join Point Kind</entry>
                    <entry>Return Type</entry>                
                    <entry>Declaring Type</entry>                
                    <entry>Id</entry>                
                    <entry>Parameter Types</entry>                
                    <entry>Field Type</entry>                
                    <entry>Exception Type</entry>                
                </row>
            </thead>
            <tbody>
                <row>
                    <entry>Method call</entry>
                    <entry>+</entry>
                    <entry>+</entry>
                    <entry>+</entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry></entry>
                </row>
                <row>
                    <entry>Method execution</entry>
                    <entry>+</entry>
                    <entry>+</entry>
                    <entry>+</entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry></entry>
                </row>
                <row>
                    <entry>Constructor call</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry></entry>
                </row>
                <row>
                    <entry>Constructor execution</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry></entry>
                </row>
                <row>
                    <entry>Field get</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                </row>
                <row>
                    <entry>Field set</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                </row>
                <row>
                    <entry>Pre-initialization</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry></entry>
                </row>
                <row>
                    <entry>Initialization</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry></entry>
                </row>
                <row>
                    <entry>Static initialization</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry></entry>
                    <entry></entry>
                    <entry></entry>
                </row>
                <row>
                    <entry>Handler</entry>
                    <entry></entry>
                    <entry></entry>
                    <entry></entry>
                    <entry></entry>
                    <entry></entry>
                    <entry>+</entry>
                </row>
                <row>
                    <entry>Advice execution</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry>+</entry>
                    <entry></entry>
                    <entry></entry>
                </row>
            </tbody>
        </tgroup>
        </informaltable>
        
        <para>Note that whilst an advice excetution join point has a
        signature comprising the declaring type of the advice and the
        advice parameter types, the <literal>adviceexecution</literal>
        pointcut designator does not support matching based on this
        signature.</para>
        
        <para>The signatures for most of the join point kinds should be
        self-explanatory, except for field get and set, and method call and execution
        join points, which can have multiple signatures. Each signature of 
        a method call or execution join point has the same id and parameter
        types, but the declaring type and return type (with covariance) may vary.
        Each signature of a field get or set join point has the same id and field
        type, but the declaring type may vary.
        </para>
        
        <para>The following sections examine signatures for these join points 
        in more detail.</para>
        
        <sect2 id="method-call-join-point-signatures" xreflabel="method-call-join-point-signatures">
            <title>Method call join point signatures</title>

        <para>
          For a call join point where a call is made to a method
          <literal>m(parameter_types)</literal> on a target type <literal>T</literal> (where
          <literal>T</literal> is the static type of the target):
        </para>

		<programlisting><![CDATA[
		T t = new T(); 
		t.m("hello");  <= call join point occurs when this line is executed
		]]></programlisting>
        
        <para>
            Then the signature <literal>R(T) T.m(parameter_types)</literal> is a signature
            of the call join point, where <literal>R(T)</literal> is the return
            type of <literal>m</literal> in <literal>T</literal>, and 
            <literal>parameter_types</literal> are the parameter types of
            <literal>m</literal>. If <literal>T</literal> itself does not
            declare a definition of <literal>m(parameter_types)</literal>, then 
            <literal>R(T)</literal> is the return type in the definition of 
            <literal>m</literal> that <literal>T</literal> inherits. Given the
            call above, and the definition of <literal>T.m</literal>:                      
        </para>
        
        <programlisting><![CDATA[
        interface Q {
          R m(String s);
        }
        
        class P implements Q {
          R m(String s) {...}        
        }
        
        class S extends P {
          R' m(String s) {...}
        }
        
        class T extends S {} 
		
		]]></programlisting>
        
        <para>Then <literal>R' T.m(String)</literal> is a signature of the
        call join point for <literal>t.m("hello")</literal>.</para>
        
        <para>
            For each ancestor (super-type) <literal>A</literal> of <literal>T</literal>, 
            if <literal>m(parameter_types)</literal> is defined for that super-type, then
            <literal>R(A) A.m(parameter_types)</literal> is a signature of the call join
            point, where <literal>R(A)</literal> is the return type of <literal>
            m(parameter_types)</literal> as defined in <literal>A</literal>, or as inherited
            by <literal>A</literal> if <literal>A</literal> itself does not
            provide a definition of <literal>m(parameter_types)</literal>.            
        </para>
        
        <para>
            Continuing the example from above,we can deduce that
        </para>

        <programlisting><![CDATA[
        R' S.m(String)
        R  P.m(String)
        R  Q.m(String)
		]]></programlisting>
        
        <para>are all additional signatures for the call join point arising
        from the call <literal>t.m("hello")</literal>. Thus this call
        join point has four signatures in total. Every signature has the same
        id and parameter types, and a different declaring type.</para>
        
       </sect2>
      
      <sect2 id="method-execution-join-point-signatures" xreflabel="method-execution-join-point-signatures">
          <title>Method execution join point signatures</title>
          
          <para>Join point signatures for execution join points are defined
          in a similar manner to signatures for call join points. Given the
          hierarchy:
          </para>


        <programlisting><![CDATA[
        interface Q {
          R m(String s);
        }
        
        class P implements Q {
          R m(String s) {...}        
        }
        
        class S extends P {
          R' m(String s) {...}
        }
        
        class T extends S { }
        
        class U extends T {
          R' m(String s) {...}
        }
		
		]]></programlisting>
        
        <para>Then the execution join point signatures arising as a result
        of the call to <literal>u.m("hello")</literal> are: </para>

        <programlisting><![CDATA[
        R' U.m(String)
        R' S.m(String)
        R  P.m(String)
        R  Q.m(String)
		]]></programlisting>

        <para>Each signature has the same id and parameter types, and a 
        different declaring type. There is one signature for each type
        that provides its own declaration of the method. Hence in this 
        example there is no signature <literal>R' T.m(String)</literal>
        as <literal>T</literal> does not provide its own declaration of
        the method.</para>

      </sect2>

       <sect2 id="field-get-and-set-join-point-signatures" xreflabel="field-get-and-set-join-point-signatures">
            <title>Field get and set join point signatures</title>

        <para>
            For a field get join point where an access is made to a field
            <literal>f</literal> of type <literal>F</literal> 
            on a object with declared type <literal>T</literal>, then
            <literal>F T.f</literal> is a signature of the get join point.  
        </para>
        
        <para>
            If <literal>T</literal> does not directly declare a member
            <literal>f</literal>, then for each super type <literal>S</literal>
            of <literal>T</literal>, up to and including the most specific
            super type of <literal>T</literal> that does declare the member
            <literal>f</literal>, <literal>F S.f</literal> is a signature
            of the join point. For example, given the hierarchy:
        </para>

        <programlisting><![CDATA[        
        class P  {
          F f;        
        }
        
        class S extends P {
          F f;
        }
        
        class T extends S { }                
		]]></programlisting>
		
		<para>
		    Then the join point signatures for a field get join point of
		    the field <literal>f</literal> on an object with declared type
		    <literal>T</literal> are:
		</para>

        <programlisting><![CDATA[
        F S.f
        F T.f
		]]></programlisting>

        <para>The signatures for a field set join point are derived in an
            identical manner.</para>
            
       </sect2>
             
      </sect1>
      
      <sect1 id="join-point-modifiers">
          <title>Join Point Modifiers</title>
          
          <para>Every join point has a single set of modifiers - these include
          the standard Java modifiers such as <literal>public, private,
          static, abstract</literal> etc., any annotations, and the throws
          clauses of methods and constructors. These modifiers are the
          modifiers of the <emphasis>subject</emphasis> of the join point.</para>
          
          <para>
          The following table defines the join point subject for each kind
          of join point.
          </para>

             <informaltable>
           <tgroup cols="2">
               <thead>
                   <row>
                       <entry>Join Point Kind</entry>
                       <entry>Subject</entry>
                   </row>
               </thead>
               <tbody>
                   <row>
                       <entry>Method call</entry>
                       <entry>The method picked out by Java as
                       the static target of the method call.</entry>
                   </row>
                   <row>
                       <entry>Method execution</entry>
                       <entry>The method that is executing.</entry>
                   </row>
                   <row>
                       <entry>Constructor call</entry>
                       <entry>The constructor being called.</entry>
                   </row>
                   <row>
                       <entry>Constructor execution</entry>
                       <entry>The constructor executing.</entry>
                   </row>
                   <row>
                       <entry>Field get</entry>
                       <entry>The field being accessed.</entry>
                   </row>
                   <row>
                       <entry>Field set</entry>
                       <entry>The field being set.</entry>
                   </row>
                   <row>
                       <entry>Pre-initialization</entry>
                       <entry>The first constructor executing in
                       this constructor chain.</entry>
                   </row>
                   <row>
                       <entry>Initialization</entry>
                       <entry>The first constructor executing in
                       this constructor chain.</entry>
                   </row>
                   <row>
                       <entry>Static initialization</entry>
                       <entry>The type being initialized.</entry>
                   </row>
                   <row>
                       <entry>Handler</entry>
                       <entry>The declared type of the
                       exception being handled.</entry>
                   </row>
                   <row>
                       <entry>Advice execution</entry>
                       <entry>The advice being executed.</entry>
                   </row>
               </tbody>
           </tgroup>
          </informaltable>          

             <para>For example, given the following types</para>

        <programlisting><![CDATA[
        public class X {        
          @Foo
          protected void doIt() {...} 
        }
        
        public class Y extends X {        
          public void doIt() {...}        
        }
		]]></programlisting>
          
         <para>Then the modifiers for a call to <literal>(Y y) y.doIt()</literal>
         are simply <literal>{public}</literal>. The modifiers for a call to
         <literal>(X x) x.doIt()</literal> are <literal>{@Foo,protected}</literal>.
         </para>
          
      </sect1>
      
      <sect1 id="join-point-matching-summary">
          <title>Summary of Join Point Matching</title>

		<para>
		A join point has potentially multiple signatures, but only one set of
		modifiers. <emphasis>A kinded primitive pointcut matches a particular join point 
		if and only if</emphasis>:
		</para>
		
		<orderedlist>
		    <listitem>They are of the same kind</listitem>
		    <listitem>The signature pattern (exactly) matches at least one 
		    signature of the join point</listitem>
		    <listitem>The modifiers pattern matches the modifiers of the
		    subject of the join point</listitem>
		</orderedlist>

        <para>Given the hierarchy</para>

        <programlisting><![CDATA[
        interface Q {
          R m(String s);
        }
        
        class P implements Q {
          @Foo
          public R m(String s) {...}        
        }
        
        class S extends P {
          @Bar
          public R' m(String s) {...}
        }
        
        class T extends S {} 
		
		]]></programlisting>

        <para>and the program fragment:</para>
        
        <programlisting><![CDATA[
        P p = new P();
        S s = new S();
        T t = new T();
        ...
        p.m("hello");
        s.m("hello");
        t.m("hello");
		]]></programlisting>
        
        <para>
        The the pointcut <literal>call(@Foo R P.m(String))</literal> matches the
        call <literal>p.m("hello")</literal> since both the signature and the 
        modifiers match. It does not match the call <literal>s.m("hello")</literal>
        because even though the signature pattern matches one of the signatures
        of the join point, the modifiers pattern does not match the modifiers of
        the method m in S which is the static target of the call.
        </para>

        <para>The pointcut <literal>call(R' m(String))</literal> matches the
        calls <literal>t.m("hello")</literal> and <literal>s.m("hello")</literal>.
        It does not match the call <literal>p.m("hello")</literal> since the
        signature pattern does not match any signature for the call join point
        of m in P.</para>
      </sect1>
  
</chapter>