Analysis

Jareento supports the efficient analysis of (large) Java software systems. Various tools collect information of the system and store the data persistently to be used for subsequent, custom analysis steps.

Analysis API

Use JavaAnalysisAPI to access Jareento's analysis features.

JavaAnalysisAPI is provided as a Java service, i.e. you may use code like the following to get access to the API:

import org.abego.jareento.javaanalysis.JavaAnalysisAPI;

import static org.abego.commons.util.ServiceLoaderUtil.loadService;

public class ClassUsingTheJavaAnalysisAPI {
    private final JavaAnalysisAPI javaAnalysisAPI = loadService(JavaAnalysisAPI.class);
    ...
}

The field javaAnalysisAPI will later be used to access the API methods.

"Project under Analysis" and JavaAnalysisProject

The source code and dependencies to analyse is called the "Project under Analysis".

In Jareento a JavaAnalysisProject is used to holds analysis information collected from a given "Project under Analysis". The JavaAnalysisProject is your main "entry point" to analysis information.

Project Configuration

Before you start an analysis you need to specify details on the "Project under Analysis". To do so you create a JavaAnalysisProjectConfiguration that includes information like where the Java source code to analyse is located, what dependencies need to be considered etc.. Later the JavaAnalysisProjectConfiguration is used to create a JavaAnalysisProject.

The following block contains an example how to create a JavaAnalysisProjectConfiguration when the code to analyse is in a Maven project.

String projectName = ...;    // every configuration gets a name, for later reference. Must follow the (Java) identifier syntax.
File projectDirectory = ...; // the Maven project directory, i.e. the directory containing the `pom.xml` file
File srcDir = ...;           // the directory containing the source code to analyse, typically "src/main/java" in the projectDirectory

JavaAnalysisProjectConfiguration projectConfiguration =
        javaAnalysisAPI.newJavaAnalysisProjectConfiguration(
                        projectName,
                        projectDirectory,
                        new File[]{srcDir});

(Other JavaAnalysisProjectConfiguration factory methods exist in case the source code to analyse is not part of a Maven project. See JavaAnalysisAPI's JavaDoc for details.)

Storage

Once you have created a JavaAnalysisProjectConfiguration you need to specify where information collected for the JavaAnalysisProject should be stored. By default, Jareento puts the information in a storage directory in the local filesystem. With code like this you specify the necessary details:

File storageDir = ...; // the directory to use for the storage 
JavaAnalysisProjectStorage storage =
        javaAnalysisAPI.javaAnalysisProjectStorage(storageDir.toURI());

Notice: you may use the same storage for multiple projects/project configurations.

Create/Load a Project

Now that you have a JavaAnalysisProjectConfiguration and a JavaAnalysisProjectStorage it is time to actually create the corresponding JavaAnalysisProject. The easiest way to do so is with code like this:

Consumer<String> progress = System.out::println; // Write progress information to `System.out`
JavaAnalysisProject project = storage.createAndLoadJavaAnalysisProject(
        projectConfiguration, progress);

Calling the storage.createAndLoadJavaAnalysisProject method creates the JavaAnalysisProject as defined by the projectConfiguration. It then starts collecting information on the project by scanning the source code, the project's jar file, the dependencies etc. The collected information is then stored in the storage.

Important: before you run the code make sure you have properly build the "Project under Analysis", especially the project's jar file must exist. Typically, you will run a mvn package to ensure this when the project under analysis is a Maven project.

Depending on the size of your "Project under Analysis" creating a JavaAnalysisProject for the first time may take a while. However, subsequent calls to storage.createAndLoadJavaAnalysisProject will be significantly faster if nothing has changed in the "Project under Analysis" in the meanwhile. In that case, no new information is collected but the existing information is loaded from the storage and reused.