MethodCallTrace4Java Files

# 00_README.txt -- This file is part of MethodCallTrace4Java.
#
# Copyright (C) 2016 Jun Inamori
#
# MethodCallTrace4Java is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published
# by the Free Software Foundation, either version 3 of the License,
# or (at your option) any later version.
#
# MethodCallTrace4Java is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty
# of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
# See the GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; see the file COPYING.
# If not, see http://www.gnu.org/licenses/.
# Or, write to the Free Software Foundation, Inc., 51 Franklin Street,
# Fifth Floor, Boston, MA 02110-1301, USA.
#

$. What it does?

In most cases, your Java project depends on the 3rd party Java classes.
You may need to clarify the relationship among those 3rd party Java classes.
And Aspect by AspectJ can shed light on your way.
This project is the template for the Aspect by AspectJ.

By the AspectJ's pointcut for the method call, you can trace back 'who' calls it.
The word 'who' in this context is:
   Which method of which class

For instance ...
By the pointcut for:
   com.thirdparty.Foo#bar()
you can trace:
   Which method of which class
calls:
   com.thirdparty.Foo#bar()

$. Requirements

This project depends on:
   AspectJ
   Ant


$. How does it work?

This project is just the set of the templates of the Aspect and Ant.
Please update the next 3 template files manually:

1) To define the pointcut for the method which we are going to trace, we need to update the source file for Aspect.
2) To define the pointcut for the 'main' method of the Java class that dispatches the program, we need to update another source file for Aspect.
3) To specify the 3rd party JAR file for the classes to be traced, we need to update the build.xml for Ant.
4) To make the adjustment for our environment, we also need to update the build.xml for Ant.

After updating the template files, it's time type:
   ant
It applies the byte weaving against the classes in the original JAR file.
The original JAR file is left untouched.
Instead, the new JAR file is created.
As default, it is:
   trace.jar
This newly created JAR file consists of the updated classes along with the Aspect classes.
Finally, you can dispatch the program by:
   java -jar trace.jar
While running the program, the tracing of the method calls are recorded into:
   aspect-yyyyMMdd.txt

In the subsequent sections, I'll describe the details.


$. pointcut for the method call

To define the pointcut for the method which we are going to trace, you need to update:
   aspect/src/com/bentofw/aspect/test/Trace4Call.java
Please modify the line like below:
   public pointcut methodToBeTraced(): call(public String com.foo.test.BagOfWord.pull());
and specify which method you are going to trace.

As for the method signature, please refer the documentaion at:
   http://www.eclipse.org/aspectj/


$. Tip about the pointcut: interface and superclass

One tip about how to trace the method calls ...
The method can be called on either of:
   the class
   the super class
   the interface
So it is safe not to assume that the method is called always against the class.
In case where you get no trace backs, please trace the method calls against:
   the super class
or:
   the interface

For instance, if you want to trace the call:
   com.thirdparty.Foo#bar()
it is worth trying to trace:
   com.thirdparty.InterfaceOfFoo#bar()
   com.thirdparty.SuperclassOfFoo#bar()


$. pointcut for the 'main' method

To define the pointcut for the 'main' method of the Java class that dispatches the program, you need to update:
   aspect/src/com/bentofw/aspect/test/Hook4Main.java
Please modify the line like below:
   public pointcut methodToBeTraced(): execution(public static void com.foo.test.AspectJChecker.main(String[]));
and specify which the class that dispatches the program.


$. build.xml for Ant

To specify the 3rd party JAR file for the classes to be traced, you need to update:
   build.xml
Please modify the line like below:
   <property name="subject_jar" value="subject/test_1_1.jar"/>

To make the adjustment for your environment, please modify the lines like below:
   <property name="aspectjrt_jar" value="/opt/usr/bin/aspectj/lib/aspectjrt.jar"/>
   <property name="lib4jar" value="/opt/usr/lib"/>
also in:
   build.xml