<aspect xmlns:src="http://www.sdml.info/srcML/src" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:cpp="http://www.sdml.info/srcML/cpp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://control.ee.ethz.ch/XWeaver/AspectX" xsi:schemaLocation="http://control.ee.ethz.ch/XWeaver/AspectX ../../../../src/xsd/aspectX.xsd" name="TraceMethodEntry">
        <description>Sample aspect program to insert tracing instructions when a selected method is
                entered. This aspect program shows an example of how the implementation of selected methods in a
                certain code base can be modified to output a tracing message every time the method is entered.
                In this example, the tracing message is output using a <code>printf</code> instruction that
                writes a message to the output device stating the name of the method and the name of the class
                to which it belongs. In this example, the identification of the methods for which tracing is to
                be performed (and which therefore must be modified by the aspect) is done "by name". This is
                probably the simplest approach in AspectX. 
                <p /> 
                This aspect defines four advices that describe four separate but related
                changes. The first advice inserts the tracing code in the target methods. The second advice
                inserts a new <code>include</code> statement to include the <code>stdio</code> library that is
                required by the <code>printf</code> method. The third advice modifies the comments of the
                classes that are affected by the change to include a statement that the class code has been
                automatically modified by an aspect program. The fourth advice modifies the comment of the
                methods that are affected by the change to include a description of the type of change that has
                been woven into the code. 
                <p /> This sample aspect program targets all methods called
                <code>fTwoParameter</code>. <author>A. Pasetti, O. Rohlik</author>
                <see>TraceClassEntry</see>
                <see>TraceConstructorEntry</see>
                <see>TraceMethodEntryUsingTracer</see>
        </description>
        
        <pointcut name="targetMethodImplementation" type="src:function" constraint="src:name/src:name[2]='fTwoParameter'">
                <description>Points to the implementations of the methods that must be modified. The methods
                        that must be modified are those whose name is: <code>fTwoParameter</code>.<p />
                        The implementation of the restriction relies on the
                        fact that in srcML the element <code>name</code> contains two other <code>name</code> subelements
                        where the first of them contains the class name and the second contains the name of the method. 
                        Therefore to access the name of the method the following expression is used:
            <code>src:name/src:name[2]</code>.
            <p /> If it were
                        desired to capture more than one target class, this could be done by modifying the XPath
                        expression in the constraint to include names whose class part matches several class names.
                        <p />
                        This pointcut only points to the method <i>implementation</i>. A second pointcut
                        (<code>targetMethodDeclaration</code>) points to the method declarations.</description>
        </pointcut>
        
        <pointcut name="targetMethodDeclaration" type="src:function_decl" constraint="src:name='fTwoParameter'">
                <description>Points to all declarations of the target methods. See the description of the
                        pointcut (<code>targetMethodImplementation</code>) but note that in srcML element
                        <code>name</code> in a declaration file directly contains the method name.
                        Hence, the constraint in the pointcut does not need to use the
                        <code>src:name/src:name[2]</code> expression.</description>
        </pointcut>
        
        <pointcut name="targetMethodComment" type="src:comment">
                <description>Points to the method comments that must be modified. The method comments that must
                        be modified are those that are followed by a <code>targetMethodDeclaration</code> pointcut. </description>
                <restriction type="followedBy">
                        <pointcutRef type="src:function_decl" ref="targetMethodDeclaration" />
                </restriction>
        </pointcut>
        
        <pointcut name="targetClass" type="src:class">
                <description>Points to all classes that contain a target method. The identification is done by
                        taking all the classes that contains a <code>targetMethodDeclaration</code> pointcut </description>
                <restriction type="contain">
                        <pointcutRef ref="targetMethodDeclaration" type="src:function_decl" />
                </restriction>
        </pointcut>
        
        <pointcut name="targetClassComment" type="src:comment">
                <description>Points to the class comments that must be modified. The class
                        comments that must be modified are those that are followed by a <code>targetClass</code>
                        pointcut. </description>
                <restriction type="followedBy">
                        <pointcutRef type="src:class" ref="targetClass" />
                </restriction>
        </pointcut>
        
        <pointcut name="targetImplementationUnit" type="src:unit">
                <description>Points to all the units that contain implementations of methods that must be
                        modified. In srcML, a <i>unit</i> is a source file (a definition file, a declaration file, or
                        an inline file). This pointcut therefore identifies all the source files that contain an
                        implementation of the target method.</description>
                <restriction type="contain">
                        <pointcutRef type="src:function" ref="targetMethodImplementation" />
                </restriction>
        </pointcut>

        <advice type="begin" name="insertTrace">
                <description>Insert the tracing instruction in the target methods. This advice inserts a printf
                        instruction at the beginning of the target method. The printf instruction prints a message
                        stating the name of the target method and of the target class. The names of the target method
                        and target class are accessed using "dollar variables".</description>
                <pointcutRef ref="targetMethodImplementation" type="src:function" />
                <codeModifier type="codeFragment">
                        <text>printf("Execution starts for method ${functionName} in class ${className}\n"); // code WOVEN by ASPECT</text>
                </codeModifier>
        </advice>
        
        <advice type="add" name="addInclude">
                <description>Add the <code>#include</code> statement for the <code>stdio</code> library.
                        Inclusion of this library is necessary because the code that is woven into the target methods
                        calls the stdio function <code>printf</code>. Note that the code to be added by this advice is
                        specified using the CDATA section because otherwise the braces around "stdio" would be
                        interpreted as xml braces by the XWeaver program.</description>
                <pointcutRef ref="targetImplementationUnit" type="src:unit" />
                <codeModifier type="include">
                        <text>#include &lt;stdio.h&gt; // code WOVEN by ASPECT</text>
                </codeModifier>
        </advice>
                
        <advice name="insertClassComment" type="end">
                <description>Add a comment at the end of the comment of the classes that are modified by other advices.</description>
                <pointcutRef ref="targetClassComment" type="src:comment" />
                <codeModifier type="comment">
                        <text>The implementation of this class has been modified by an aspect
program. The aspect program adds code to trace the execution of the "fTwoParameter" method. See
the method comment for more details. (comment WOVEN by ASPECT)</text>
                </codeModifier>
        </advice>
        
        <advice name="insertMethodComment" type="end">
                <description>Add a comment at the end of the comment of the methods that are modified by other advices.</description>
                <pointcutRef ref="targetMethodComment" type="src:comment" />
                <codeModifier type="comment">
                        <text>The implementation of this method has been modified by an aspect
program. The aspect program adds a statement that prints a message to the standard output
stating the name of this method and of this class. The statement is inserted at the very
beginning of the method. This message can be used to trace executions of the method during 
debugging. (comment WOVEN by ASPECT)</text>
                </codeModifier>
        </advice>
        
</aspect>