TraceClassEntry Aspect
[CodeInstrumentation Group]

This aspect is defined in file: ../../AspectXLib/CodeInstrumentation/Base/aspects/TraceClassEntry.ax

Aspect Description

Sample aspect program to insert tracing instructions when a selected class is entered. This aspect program shows an example of how the implementation of a class in a certain code base can be modified to output a tracing message every time one of its methods is entered. In this example, the tracing message is output using a printf 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 target class for which tracing is to be performed (and which therefore must be modified by the aspect) is done "by name". The aspect only covers the case of a single target class but it could be easily modified to cover several target classes.

This aspect defines four advices that describe four separate but related changes. The first advice inserts the tracing code in the methods of the target class. The second advice inserts the tracing code in the constructors of the target class. The third advice inserts a new include statement to include the stdio library that is required by the printf method. The fourth advice modifies the comment of the target class to include a statement that the class code has been automatically modified by an aspect program.

This sample aspect program targets a class called Derived.
Author:
A. Pasetti, O. Rohlik
See also:
TraceMethodEntry
TraceConstructorEntry
TraceMethodEntryUsingTracer

Pointcuts

functiontargetMethodImplementation
 Points to the implementations of the methods in the target class
constructortargetConstructorImplementation
 Points to the constructors of the target class
classtargetClass
 Points to the target class to be modified by this aspect program
commenttargetClassComment
 Points to the comment of the target class
unittargetImplementationUnit
 Points to the unit that contains the implementations of the target class

Advices

begininsertMethodTrace
 Insert the tracing instruction in the target methods
begininsertConstructorTrace
 Insert the tracing instruction in the target construtors
addaddInclude
 Add the #include statement for the stdio library
endinsertClassComment
 Add a comment at the end of the comment of the target class

Pointcut Documentation

function targetMethodImplementation (source)
Points to the implementations of the methods in the target class. The identification of the methods in the target class is done as follows. A pointcut is defined that captures all method implementations. This pointcut is then restricted to include only methods that belong to the target class. The implementation of the restriction relies on the fact that in srcML the element name contains two other name 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 class the following expression is used: src:name/src:name[1].

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.

Note that this pointcut only points to the method implementation. There is no need to capture the method declarations since this aspect program does not make any modifications to the method declarations or to their comments.
constructor targetConstructorImplementation (source)
Points to the constructors of the target class. The identification of the constructors in the target class is done as follows. A pointcut is defined that captures all constructor implementations. This pointcut is then restricted to include only methods that belong to the target class. The implementation of the restriction relies on the fact that in srcML the element name contains the fully qualified name of the constructors and methods. This has the form "CCC::CCC" where "CCC" is the class name.

This pointcut only points to the class constructors. This excludes the class destructors because srcML treats them separately. Another dedicated pointcut would be required if it were desired to insert the tracing message in the destructor.

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.
class targetClass (source)
Points to the target class to be modified by this aspect program. This is a very simple pointcut that captures all classes and then adds the restriction that the name of the class must be equal to "Derived". Note that this pointcut points to the class declaration only, not the class implementation. The class implementation is captured by the targetMethodImplementation pointcut that points to the implementation of the methods in the target class.
comment targetClassComment (source)
Points to the comment of the target class. This pointcut is necessary because this aspect program contains an advice that modifies the comment of the target class. The target comment is identified as the comment that is followed by the target class.
unit targetImplementationUnit (source)
Points to the unit that contains the implementations of the target class. In srcML, a unit 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 or constructor.

Advice Documentation

begin insertMethodTrace (source)

Triplet: function begin codeFragment

Insert the tracing instruction in the target methods. This advice inserts a printf instruction at the beginning of the target methods. 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".

Refers to global pointcut: function targetMethodImplementation

begin insertConstructorTrace (source)

Triplet: constructor begin codeFragment

Insert the tracing instruction in the target construtors. This advice inserts a printf instruction at the beginning of the target construtors. The printf instruction prints a message stating the name of the target class. The name of the target class is accessed using XSL instruction value-of with XPath expression that extracts the class name from scrML. See also the pointcut targetConstructorImplementation.

Refers to global pointcut: constructor targetConstructorImplementation

add addInclude (source)

Triplet: unit add include

Add the #include statement for the stdio library. Inclusion of this library is necessary because the code that is woven into the target class calls the stdio function printf. 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.

Refers to global pointcut: unit targetImplementationUnit

end insertClassComment (source)

Triplet: comment end comment

Add a comment at the end of the comment of the target class. The comment thus inserted in the target class states that the class has been automatically modified by an aspect program and describes the nature of the modification. Note that this aspect program defines no modifications to the comments of the methods in the target class.

Refers to global pointcut: comment targetClassComment