<aspect xmlns:cpp="http://www.sdml.info/srcML/cpp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://control.ee.ethz.ch/XWeaver/AspectX" xmlns:src="http://www.sdml.info/srcML/src" xsi:schemaLocation="http://control.ee.ethz.ch/XWeaver/AspectX ../../../../src/xsd/aspectX.xsd" name="TraceMethodEntryUsingTracer">
         

        <description>Sample aspect program that shows how to insert instructions that use dedicated 
        <code>Tracer</code> object for tracing. This example is implemented according to the 
        <a href="http://www.pnp-software.com/ObsFramework/doc/Trace.html">Trace design pattern</a>
        <p />
        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 dedicated object of type 
                <a href="http://www.pnp-software.com/ObsFramework/doc/doxygen/html/classDC__TestTracer.html"><code>DC_TestTracer</code></a>
                that encapsulates the code that process the tracing messages. 
                <code>DC_TestTracer</code> class extends the 
        <a href="http://www.pnp-software.com/ObsFramework/doc/doxygen/html/classTracer.html"><code>Tracer</code></a>
        abstract class, which is a part of the 
        <a href="http://www.pnp-software.com/ObsFramework/">OBS Framework</a>. 
            An instance of class <code>DC_TestTracer</code> is accessed through the <code>TracerSingleton</code> class. 
        Hence the <code>TracerSingleton</code> is used as a component that sends the trace 
                signals to a log file or standard output.        
        See the <a href="http://www.pnp-software.com/ObsFramework/doc/Trace.html">Trace 
                design pattern</a> for more information. 
                <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>TraceMethodEntry</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 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="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="add" name="addIncludeRootObject">
             <description>Add the <code>#include "TracerSingleton.h"</code> preprocessor directive.
                        The inclusion of this header file is necessary because the code that is woven into the target methods
                        uses the static method <code>getInstance()</code> declared in the this file.</description>
                <pointcutRef ref="targetImplementationUnit" type="src:unit" />
                <codeModifier type="include">
                        <text>#include "TracerSingleton.h"                                                                // code WOVEN by ASPECT </text>
                </codeModifier>
        </advice>
        
        <advice type="begin" name="insertTrace">
            <description>Insert the tracing instruction in the target method. This advice defines a tracing signal item 
                at the beginning of the target method. Then the item is send to the Tracer object using the 
                <code>sendSynchTrace()</code> method. The <code>Tracer</code> object is encapsulated in the 
                <code>TracerSingleton</code> 
                class. Thus only one <code>Tracer</code> object is available to the whole application.
        </description>
                <pointcutRef ref="targetMethodImplementation" type="src:function" />
                <codeModifier type="codeFragment">
                        <text>TD_TraceItem item = 0x0000;                                                                // code WOVEN by ASPECT 
TracerSingleton::getInstance()-&gt;sendSynchTrace(item);        // code WOVEN by ASPECT</text>
                </codeModifier>
        </advice>

</aspect>