TraceMethodEntry Aspect
[CodeInstrumentation Group]

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

Aspect 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 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 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.

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 include statement to include the stdio library that is required by the printf 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.

This sample aspect program targets all methods called fTwoParameter.
Author:
A. Pasetti, O. Rohlik
See also:
TraceClassEntry
TraceConstructorEntry
TraceMethodEntryUsingTracer

Pointcuts

functiontargetMethodImplementation
 Points to the implementations of the methods that must be modified
function_decltargetMethodDeclaration
 Points to all declarations of the target methods
commenttargetMethodComment
 Points to the method comments that must be modified
classtargetClass
 Points to all classes that contain a target method
commenttargetClassComment
 Points to the class comments that must be modified
unittargetImplementationUnit
 Points to all the units that contain implementations of methods that must be modified

Advices

begininsertTrace
 Insert the tracing instruction in the target methods
addaddInclude
 Add the #include statement for the stdio library
endinsertClassComment
 Add a comment at the end of the comment of the classes that are modified by other advices
endinsertMethodComment
 Add a comment at the end of the comment of the methods that are modified by other advices

Pointcut Documentation

function targetMethodImplementation (source)
Points to the implementations of the methods that must be modified. The methods that must be modified are those whose name is: fTwoParameter.

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 the name of the method. Therefore to access the name of the method the following expression is used: src:name/src:name[2].

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.

This pointcut only points to the method implementation. A second pointcut (targetMethodDeclaration) points to the method declarations.
function_decl targetMethodDeclaration (source)
Points to all declarations of the target methods. See the description of the pointcut (targetMethodImplementation) but note that in srcML element name in a declaration file directly contains the method name. Hence, the constraint in the pointcut does not need to use the src:name/src:name[2] expression.
comment targetMethodComment (source)
Points to the method comments that must be modified. The method comments that must be modified are those that are followed by a targetMethodDeclaration pointcut.
class targetClass (source)
Points to all classes that contain a target method. The identification is done by taking all the classes that contains a targetMethodDeclaration pointcut
comment targetClassComment (source)
Points to the class comments that must be modified. The class comments that must be modified are those that are followed by a targetClass pointcut.
unit targetImplementationUnit (source)
Points to all the units that contain implementations of methods that must be modified. 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.

Advice Documentation

begin insertTrace (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 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".

Refers to global pointcut: function targetMethodImplementation

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 methods 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 classes that are modified by other advices.

Refers to global pointcut: comment targetClassComment

end insertMethodComment (source)

Triplet: comment end comment

Add a comment at the end of the comment of the methods that are modified by other advices.

Refers to global pointcut: comment targetMethodComment