Reporting using the API

Reporting in JPlag can be used to create report files from a JPlagResult, which can then be easily saved, transferred or supplied to an application for displaying. Currently JPlag support reporting in JSON format. Further formats can be specified.
Reporting can be done through the Report interface. It provides two functions - getReportStrings and saveReport.

• getReportStrings - takes a JPlagResult, converts it to a JPlagReport and returns a list of strings, where
  first string is the overview string and the remaining elements are the strings of
  the comparison reports. The strings rpresent the JSON serialization of the JPlagReport
• saveReport - uses the getReportString to obtain the JSON strings
  of the report and saves them to JSON files in the provided folder path.

Example:

Report report = new JsonReport();

// Returns JSON strings in a list
List<String> jsonStrings = report.getReporStrings(jplagResult);

// Saves JSON strings of the report in the specified folder
report.saveReport(jPlagResult, "./path/to/destination/folder");

Running the Report Viewer

The JPlag Report Viewer is a Vue 3 + Typescript standalone application which can be used to display the JSON files generated by the JPlag reporting. The application requires Node.js and npm to be installed on the system.

• Before first run execute: npm i.
• To start the application, run the npm run serve command in the /report-viewer folder.

After the application has been started the user can select files to display in the following ways:

• by providing overview.json and comparisons JSON files in the /report-viewer/files folder
• by dragging and dropping a zip file containing the overview.json and comparisons JSON files
• by dragging and dropping a single overview.json or a single comparison JSON file

Start page of the application

Change

File outputDir = new File("/path/to/output");
Report report = new Report(outputDir);

report.writeResult(result);

with

Report report = new JsonReport();
report.saveReport(result, "/path/to/output")

Reporting design

The CLI uses the Report, which takes a JPlagResult in order to create report files. Currently JPlag supports reporting in JSON format. JsonReport implements the Report interface. Upon receiving the JPlagResult, the JsonReport uses the ReportObejctFactory in order to convert the JPlagResult in a simple Java DTO JPlagReport. After that the created JPlagReport is passed to the JsonFactory which converts the Java DTO JPlagReport to JSON strings and saves the files with the JACKSON library. The OverviewReport of the JPlagReport is saved as overveiw.json. Each ComparisonReport is saved as {id1}-{id2}.json where id1 is the name of the first submission in the comparison and id2 is the second submission's name. The class diagram represents the strucutre of the report generation process. The process flow can be observed in the following sequence diagram.

Class Diagram

classDiagram
    class CLI
    class Report
    class JPlagResult
    class JsonReport
    class JsonFactory
    class ReportObjectFactory
    class JPlagReport
    class overview {
    <<json file>>
    }
    class comparison {
        <<json file>>
    }
    
    CLI ..> Report : uses
    Report --> JPlagResult
    JsonReport ..|> Report
    JsonReport ..> JsonFactory
    JsonReport ..> ReportObjectFactory
    ReportObjectFactory --> JPlagReport : creates
    ReportObjectFactory ..> JPlagResult: uses
    JsonFactory --> JPlagReport : uses
    JsonFactory .. "1" overview : creates
    JsonFactory .. "*" comparison : creates

Sequence Diagram

sequenceDiagram
    CLI ->>+ JsonReport: saveReport(jplagResult)
    JsonReport ->>+ ReportObjectFactory: getReportObejct(jplagResult)
    ReportObjectFactory ->>+ JPlagReport: new JPlagReport()
    JPlagReport ->>+ ReportObjectFactory: jPlagReport
    ReportObjectFactory ->>+ JsonReport: jPlagReport
    JsonReport ->>+ JsonFactory: saveJsonFiles(jPlagReport)
    JsonFactory ->>+ JsonReport: boolean
    JsonReport ->>+ CLI: boolean

JPlagReport

A report in JPlag is represented by the JPlagReport class, which contains a single overview and a list of comparison reports. The overview encapsulates the main information from a JPlagResult such as base directory path, language, metrics used, etc. The comparison report encapsulates the information about a single comparison such as participating submissions, their files, similarity and matches between them. The full structure of the JPlagReport DTO can be observed in the following class diagram.

JPlagReport report = ReportObjectFactory.getReportObject(jPlagResult);

classDiagram
    class JPlagReport {

    OverviewReport overviewReport;
    List<ComparisonReport> comparisons;

    }
    class OverviewReport {
    
    }

    class ComparisonReport {

    }
    class Metric {

    }
    class Cluster { 

    }
    class Match {
      
    }
    class TopComparison {
        
    }
    class FilesOfSubmission {
        
    }
    JPlagReport --|> OverviewReport
    JPlagReport --|> ComparisonReport
    OverviewReport --|> Metric
    OverviewReport --|> Cluster
    Metric --|> TopComparison
    ComparisonReport --|> Match
    ComparisonReport --|> FilesOfSubmission

Specifying additional report formats

In order to specify a new report format (example: XML reporting), the report interface needs to be implemented. The existing logic for converting a JPlagResult to JPlagReport can be reused and the created DTO can be used as an input to a factory creating the new report format.

Report viewer

The report viewer accepts JSON files and displays them. When a JSON file is provided, the application uses the OverviewFactory or ComparisonFactory in order to convert the JSON file to a Typescript DTO. The DTOs are then used by the view components to get the needed information.

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:

1. Introduce new attribute to the Java DTO.
2. Define how the attribute is obtained from the JPlagResult in the ReportObjectFactory.
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 private final int tokens; to Match.java [JPlag]
2. Add a getter for the field in Match.java [JPlag]
3. Edit the convertMatchToReportMatch in ReportObejctFactory to get then umber of tokens from de.jplag.Match
   and save it in the Match DTO [JPlag]
4. Add tokens: number to Match.ts [report-viewer]
5. Edit mapMatch in ComparisonFactory.ts to get the number of tokens from the JSON report file. [report-viewer]
6. Edit MatchTable.vue to display the tokens number in the ComparisonView.