2. Contributing to JPlag

[cholakov11]

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.

[watob]

Reporting design

I would suggest to use uppercase in headlines.

The overview encapsulates the main information from a JPlagResult such as base directory path, language, metrics used, etc.

I like the idea of using italic type for the classes. It would be nice if you could keep that consistent throughout the documentation.

In "Adding and displaying new attributes from JPlagResult" I would suggest using a consistent tense. So either adding or added.

[sebinside]

Here is some more feedback:

• Please ensure that all edges in the first diagram follow the correct UML class diagram syntax (e.g., inheritance, implementation, association, ...)
• In the second class diagram, I would suggest simplifying the classes, e.g., by removing or shortening the list of attributes. The current, full representation (e.g., 20 entries in the OverviewReport) will probably cause documentation drift someday and also does not help in giving an overview.
• There is a large space below the second diagram
• I really like the section about adding new attributes. Maybe you can make it more clear, that the second half is an example, e.g., by adding another subtitle?
• When speaking about how data is sent from the JPlag analysis to the serialization, to the files, to the Report Viewer, a activity or sequence diagram would also be a nice addition

[tsaglam]

Please ensure that all edges in the first diagram follow the correct UML class diagram syntax (e.g., inheritance, implementation, association, ...)

Here is the Syntax for UML in Mermaid: https://mermaid-js.github.io/mermaid/#/classDiagram