AspectJ Partially Ordered Logging tool (AJPOLog)

AJPOLog is a collection of tools for instrumenting Java programs. It consists of three parts:

• An Eclipse project for instrumenting Java programs
• A Python script for converting raw logs into CSV files that ProM can read
• A Jupyter (Python) Notebook for mapping packages to architectural elements and drawing graphs from logs

How to instrument a Java program

We will be using Eclipse, mostly to save ourselves from having to configure build tools and class paths manually.

1. Find a Java program of which you have the source code. This will be referred to as the system under study (SUS) Preferably with clear instructions on how to build from source in Eclipse
2. Add the required instrumentation tools
   1. Install AspectJ tools for Eclipse
   2. Follow the build instructions for the SUS
   3. Make sure both AJPOLog and the SUS are correctly imported as projects in Eclipse
   4. Convert the SUS project into an AspectJ project (requires AspectJ plugin for Eclipse)
   5. In JabRef’s case, for example:
      1. Follow instructions to setting up a local workspace (https://github.com/JabRef/jabref/wiki/Guidelines-for-setting-up-a-local-workspace)
      2. Right click the project in the Package Explorer > Configure > Convert to AspectJ project
      3. Right-click the project again > Properties > AspectJ Build > Aspect Path > Add Project > Select AJPOLog
      4. Click ‘Apply and close’
3. Create a scenario
   1. Define what parts of the SUS need to be included in the architecture model. In dynamic architecture reconstruction, only elements that appear in the log can be included in the generated architecture model.
   2. Create a scenario (a set of interactions between the user and the SUS) that covers these parts
   3. Run the instrumented version of the SUS
   4. Execute the scenario
   5. Stop the SUS
4. Extract the log
   1. Find the log file generated by the instrumented system
   2. Convert this log file into a more ProM-friendly format using a Python script
      1. If the log is incomplete (the SUS stopped unexpectedly), the script will attempt to fix it

Log conversion script instructions

In the scripts folder, there is a Python script called convert.py. You can run it from your command line if you have Python installed. The tool requires a single argument: the filename or full path to the file you want to convert. The script will then output a converted file in the same location as the input file.

Using the notebook

All instructions for using the notebook are included in the Notebook itself. Jupyter Notebook under Python 3 is required to open it.