6. Report File Generation

ReportObjectFactory is the starting point and anchor for the reporting process. CLI calls ReportObjectFactory#createAndSaveReport(result: JPlagResult, path: String), providing the factory with the result of the JPlag run and the desired target path for the report. ReportObjectFactory#createAndSaveReport then goes on and delegates the creation of all necessary files and folders, and consequently packs the report.

Report File Structure

result.jplag
|   cluster.json
|   distribution.json
|   options.json
|   runInformation.json
|   submissionFileIndex.json
|   submissionMappings.json
|   topComparisons.json
│
└───comparisons
|   └───submission1-submission2.json
│       submission1-submission3.json
│       submission1-submission....json
│       submission1-submissionN.json
│       submission2-submission3.json
│       submission2-submission....json
│       submission2-submissionN.json
|       ...
|
└───files
│   └───submissionId1
│       │   submission1File1
│       │   submission1File2
│       │   ...
│   └───submissionId2
│       │   submission2File1
│       │   submission2File2
│       │   ...
│   └───submissionId...
│       │   ...
│   └───submissionIdN
│       │   submissionNFile1
│       │   submissionNFile2
│       │   ...
│
└───basecode
│   └───submissionId1.json
│   └───submissionId2.json
│   ...

The report file contains

• cluster.json

  • This file contains a list of all Clusters found by JPlag. It is an array filled with instances of Cluster.

• distribution.json

  • This file contains the distribution of the similarities of all comparisons for several metrics. Each distribution has 100 buckets, on for each percentile. It is a Map from the metric name to an array of integers.

• options.json

  • This File contains all options given to JPlag either over the CLI or programmatically. It is represented directly by the JPlagOptions class.

• runInformation.json

  • This file contains information about the JPlag run, such as the time it took to run and the number of comparisons. It corresponds to the Java record RunInformation.

• submissionFileIndex.json

  • The submissionFileIndex.json stores a list of all files in the submission for each submission id. This file is also used to track the tokens per file. It is represented by a Map from the submission id to an instance of SubmissionFile.

• submissionMappings.json

  • This file contains one Map from the submission id to the display name of the submission. A second map contains the file name for each comparison based on the submission ids. It is a Map<String, Map<String, String>>.

• topComparisons.json

  • This file contains a list of the exported comparisons. For each comparison it hold the submissions names and their similarities. It contains instances of the Java record TopComparison.

• comparisons

  • This folder contains a detailed report for each exported comparison. For each submission pair submission1 submission2 with ids submissionId1 and submissionId2, the report contains either submissionId1-submissionId2.json or submissionId2-submissionId1.json. This file contains information on the comparison between the two submissions, such as the similarity and concrete matches. Corresponds to the Java record ComparisonReport.

• files

  • This folder contains all files of all submissions that JPlag was run on. For each submission, the submissions folder contains a subfolder with the name of the corresponding submission id. A subfolder for a submission contains all files of said submission. These files are displayed in the ComparisonView.vue

• base code

  • Each JSON file in the basecode folder contains the data where the provided basecode was found in each submission. Each submission has its own file. If no basecode was provided, each file contains an empty array of matches. Each JSON file corresponds to an array of the Java record BaseCodeMatch.

Submission ids

Report Viewer

The overview.json contains a map that associates a submission id to its display name. For internal use in the report viewer, use only (!) the submission id. Whenever the name of a submission has to be displayed in the report viewer, the id has to be resolved to its display name first. The report viewer's vuex store provides a getter for this resolution.

JPlag

At the beginning of report generation, a map and a function that associates a JPlag Submission to a submission id is built. Whenever you reference a submission in a report viewer DTO use this map/function to resolve the submission to its id.

Adding and displaying new attributes from JPlagResult

The new design of JPlag reporting and viewing enables the easy addition of new attributes. Adding a new attribute follows the pattern:

In JPlag:

1. Introduce a new attribute to the Java DTO that represents the file you aim to change.
2. Define how the attribute is obtained from the JPlagResult. Do so either by introducing a new component that extracts the attribute from the JPlagResult or by modifying an existing component. ReportObjectFactory then calls this component and assigns the result to the attribute defined in 1.

In the Report Viewer:

3. Introduce the new attribute to the Typescript DTO.
4. Define how the attribute is extracted from the JSON file.
5. Display the attribute in the desired Vue component.

Example

An example is provided in the following section, which explains how new attributes can be introduced to the JPlagReport and then processed in the report viewer. In the following example we add the number of tokens per match to the JPlag report and view.

Task: Adding the number of tokens in a match, which has to be displayed in the MatchesTable in the ComparisonView.

1. Add int tokens to Match.java (sub-model of ComparisonReport.java)
2. Modify the existing component ComparisonReportWriter.java to additionally extract the number of tokens in a match from the JPlagResult.java and save it in the Match DTO
3. Add tokens: number to Match.ts
4. Edit ComparisonFactory.ts to get the number of tokens from the JSON report file.
5. Edit MatchList.vue to display the tokens number in the ComparisonView.vue.