FASTEN Beta-testing Campaign #1 Instructions

This page presents the instructions to successfully run and experiment with Java call graph generator beta version. You will find indications guiding you through the 3 different steps and test scenarios, going from the simplest to the more advanced. We recommend that you follow instructions from top to bottom, but each scenario is independent so you can safely skip one.

Test #1: execution with basic local application and dependency

In this first test you will use a very basic locally downloaded Java application and its dependency.

Download:
- The application jar file
- The application dependency jar file
and put both files in the same folder as javacg-opal-0.0.1-beta1-with-dependencies.jar.

You can take a look at the source code of my-app and my-lib in order to compare it with the output you will get from Java call graph generator.

Now you can run: java -jar javacg-opal-0.0.1-beta1-with-dependencies.jar -ga RTA -a my-app-1.0.0.jar -d my-lib-2.0.0.jar -i FILE -ma CHA -m -o ./output.json

This will execute the Java call graph generator and analyze the locally available application and its dependency jar files. The call graph will be generated using RTA algorithm and merging between application and library call graph will be done using CHA algorithm.
Result of the execution will be stored in a JSON file named: output.json
Note: you can use Python to pretty print the JSON: cat output.json | python -m json.tool > output-pretty-print.json

If you open the JSON file you can see first the list of methods and constructors (important: your id values might be different):
- JSON object named externalTypes includes information defined in the library or by the Java API. In our example you should find:
  - /io.ow2.amottier.sandbox.mylib/Speaker.%3Cinit%3E()%2Fjava.lang%2FVoidType with id 4: library unique class constructor: Speaker().
  - /io.ow2.amottier.sandbox.mylib/Speaker.sayHello()%2Fjava.lang%2FVoidType with id 5: library unique method: sayHello.
  - /java.lang/Object.%3Cinit%3E()VoidType with id 3: Java Object class constructor.
- JSON object named internalTypes includes information defined in the main application:
  - /io.ow2.amottier.sandbox.myapp/MyApp.%3Cinit%3E()%2Fjava.lang%2FVoidType with id 0: constructor of the main application: MyApp().
  - /io.ow2.amottier.sandbox.myapp/MyApp.main(%2Fjava.lang%2FString%5B%5D)%2Fjava.lang%2FVoidType with 1: main method.
  - /io.ow2.amottier.sandbox.myapp/MyApp.run()%2Fjava.lang%2FVoidType with id 2: run method called by main method.

You should finally find in the JSON file the call graph information. Calls are grouped in two categories:
- internal: calls within the main application.
- external: calls from main application to library or to Java API.

In our example you should get the following call:
- internals:
  - 1 -> 0: main method calling the MyApp constructor.
  - 1 -> 2: main method calling the run method defined in MyApp.
- externals:
  - 0 -> 3: MyApp constructor calling Object constructor.
  - 0 -> 4: MyApp constructor calling Speaker constructor.
  - 2 -> 5: run method calling sayHello.

If you compare the JSON output with the actual calls from the source code (my-app and my-lib) you should be able to validate that the tool properly identified all calls.

Next test will use a publicly available library from Maven Central instead of dummy local application.

Test #2: execution with Maven public artifact

Now we will run the Java call graph generator against a publicly available library (i.e. published on Maven Cental).

We will use HttpClient as a the library for our test. Version 5.0.3 of this library have a dependency on HttpCore version 5.0.2 so we should be able to see calls from HttpClient to HttpCore in the output of the call graph generator.

Run the following command: java -jar javacg-opal-0.0.1-beta1-with-dependencies.jar -ga RTA -a "org.apache.httpcomponents.client5:httpclient5:5.0.3" -d "org.apache.httpcomponents.core5:httpcore5:5.0.2" -i COORD -ma CHA -m -o ./output-apache.json

Above command will download jar files from Maven Central, generate the call graph and store the result in output-apache.json file.

You can now open the file (optionally after formatting it using Python json.tool).

In the file, you can then search for /org.apache.hc.client5.http.impl.async/MinimalH2AsyncClient.execute(%2Forg.apache.hc.core5.http.nio%2FAsyncClientExchangeHandler,%2Forg.apache.hc.core5.http.nio%2FHandlerFactory,%2Forg.apache.hc.core5.http.protocol%2FHttpContext)%2Forg.apache.hc.core5.concurrent%2FCancellable method. Write down the id generated for this method by the call graph generator, you will need it later on. You can take a look at the source code of this method in GitHub.

Still in the JSON file, you should be able to find /org.apache.hc.core5.http.nio/AsyncClientExchangeHandler.produceRequest(RequestChannel,%2Forg.apache.hc.core5.http.protocol%2FHttpContext)%2Fjava.lang%2FVoidType method. Also write down the id.

If you now take a look at the source code of MinimalH2AsyncClient.execute on line 147 you can see a call to AsyncClientExchangeHandler.produceRequest, a class and method of HttpCore.

Finally in the JSON file, you should be able to confirm that the call from MinimalH2AsyncClient.execute to AsyncClientExchangeHandler.produceRequest as been identified as you should have a pair of id that match the id you wrote down in the previous steps.

At this point you might want to do more comparison between the source code and call graph generator output. If you find any missing calls, please report them by opening an issue on the tracker.

And now you should be ready to experiment with your own software.

Test #3: execution with your own project

You can reuse commands previously executed to experiment with your own software. If your application has several dependencies, you can provide a comma separated list of dependencies, e.g.: java -jar javacg-opal-0.0.1-beta1-with-dependencies.jar -ga RTA -a my-own-app-1.0.0.jar -d my-lib-A-2.0.0.jar,my-other-lib-B-1.3.9.jar -i FILE -ma CHA -m -o ./output.json

While you are experimenting with your own software, you might face specific issues related to your code. If such issues arise, we will really appreciate reports on the project bug tracker. If you can provide, in your issue report, packaged version of your software as well as source code that would be really helpful.

Thanks for evaluating the FASTEN call graph generator and stay tuned for more FASTEN beta testing campaign (including Maven plugin)!