add comments

Author: Cathy0123456789

src/main/java/de/tum/cit/aet/dataProcessing/service/RequestService.java

@@ -1,5 +1,6 @@
 package de.tum.cit.aet.dataProcessing.service;
 
+import de.tum.cit.aet.analysis.dto.AuthorContributionDTO;
 import de.tum.cit.aet.analysis.service.AnalysisService;
 import de.tum.cit.aet.core.dto.ArtemisCredentials;
 import de.tum.cit.aet.repositoryProcessing.domain.*;
@@ -36,6 +37,22 @@ public RequestService(RepositoryFetchingService repositoryFetchingService, Analy
         this.studentRepository = studentRepository;
     }
 
+    /**
+     * Fetches, analyzes, and saves repository data using the provided Artemis credentials.
+     *
+     * @param credentials The Artemis credentials
+     */
+    public void fetchAnalyzeAndSaveRepositories(ArtemisCredentials credentials) {
+        // Fetch and clone repositories
+        List<TeamRepositoryDTO> repositories = fetchAndCloneRepositories(credentials);
+
+        // Analyze contributions
+        Map<Long, AuthorContributionDTO> contributionData = getContributionData(repositories);
+
+        // Save results to the database
+        saveResults(repositories, contributionData);
+    }
+
     /**
      * Fetches and clones all repositories from Artemis using dynamic credentials.
      *
@@ -53,42 +70,25 @@ public List<TeamRepositoryDTO> fetchAndCloneRepositories(ArtemisCredentials cred
      * @param repositories List of TeamRepositoryDTO to be analyzed
      * @return Map of Participant ID to an array of contribution metrics (e.g., lines added, lines deleted)
      */
-    public Map<Long, int[]> getContributionData(List<TeamRepositoryDTO> repositories) {
+    public Map<Long, AuthorContributionDTO> getContributionData(List<TeamRepositoryDTO> repositories) {
         return analysisService.analyzeContributions(repositories);
     }
 
-    /**
-     * Fetches, analyzes, and saves repository data using the provided Artemis credentials.
-     *
-     * @param credentials The Artemis credentials
-     */
-    public void fetchAnalyzeAndSaveRepositories(ArtemisCredentials credentials) {
-        // Fetch and clone repositories
-        List<TeamRepositoryDTO> repositories = fetchAndCloneRepositories(credentials);
-
-        // Analyze contributions
-        Map<Long, int[]> contributionData = getContributionData(repositories);
-        for (int[] lines : contributionData.values()) {
-            log.info("Contribution Data - Added Lines: {}, Deleted Lines: {}", lines[0], lines[1]);
-        }
-
-        // Save results to the database
-        saveResults(repositories, contributionData);
-    }
-
     /**
      * Saves the fetched repository information into the database.
      *
      * @param repositories     List of TeamRepositoryDTO to be saved
      * @param contributionData Map of Participant ID to an array of contribution metrics (e.g., lines added, lines deleted)
      */
-    public void saveResults(List<TeamRepositoryDTO> repositories, Map<Long, int[]> contributionData) {
+    public void saveResults(List<TeamRepositoryDTO> repositories, Map<Long, AuthorContributionDTO> contributionData) {
+        // Clear existing data in database tables. We assume a full refresh of all data is intended, effectively treating the run as idempotent
         teamRepositoryRepository.deleteAll();
         studentRepository.deleteAll();
         teamParticipationRepository.deleteAll();
         tutorRepository.deleteAll();
 
         for (TeamRepositoryDTO repo : repositories) {
+            // Save tutor
             ParticipantDTO tut = repo.participation().team().owner();
             Tutor tutor = null;
             if (tut == null) {
@@ -98,25 +98,35 @@ public void saveResults(List<TeamRepositoryDTO> repositories, Map<Long, int[]> c
                 tutorRepository.save(tutor);
             }
 
+            // Save team participation
             ParticipationDTO participation = repo.participation();
             TeamDTO team = participation.team();
             TeamParticipation teamParticipation = new TeamParticipation(participation.id(), team.id(), tutor, team.name(), team.shortName(), participation.repositoryUri(), participation.submissionCount());
             teamParticipationRepository.save(teamParticipation);
 
+            // Save students with contributions
             List<Student> students = new ArrayList<>();
             for (ParticipantDTO student : repo.participation().team().students()) {
-                int[] lines = contributionData.get(student.id());
-                if (lines == null) {
-                    lines = new int[]{0, 0, 0};
+                AuthorContributionDTO contributionDTO = contributionData.get(student.id());
+
+                // Handle the case where a student made no contributions (e.g., if they were registered but never committed)
+                if (contributionDTO == null) {
+                    contributionDTO = new AuthorContributionDTO(0, 0, 0);
                 }
-                students.add(new Student(student.id(), student.login(), student.name(), student.email(), teamParticipation, lines[2], lines[0], lines[1], lines[0] + lines[1]));
+
+                students.add(new Student(student.id(), student.login(), student.name(), student.email(), teamParticipation,
+                        contributionDTO.commitCount(), contributionDTO.linesAdded(), contributionDTO.linesDeleted(),
+                        contributionDTO.linesAdded() + contributionDTO.linesDeleted()));
             }
             studentRepository.saveAll(students);
 
+            // Save team repository
             TeamRepository teamRepo = new TeamRepository(teamParticipation, null, repo.localPath(), repo.isCloned(), repo.error());
 
+            // Process VCS logs
             List<VCSLog> vcsLogs = repo.vcsLogs().stream().map(log -> new VCSLog(teamRepo, log.commitHash(), log.email())).toList();
 
+            // Save the TeamRepository (through cascade, VCSLogs will also be saved)
             teamRepo.setVcsLogs(vcsLogs);
             teamRepositoryRepository.save(teamRepo);
 
@@ -125,17 +135,17 @@ public void saveResults(List<TeamRepositoryDTO> repositories, Map<Long, int[]> c
     }
 
     /**
-     * Extracts all saved repository and contribution data from the database.
+     * Retrieves all stored repository data from the database and assembles it into ClientResponseDTOs.
      *
-     * @return A list of ClientResponseDTOs containing all aggregated team and student data.
+     * @return List of ClientResponseDTO containing the assembled data
      */
     public List<ClientResponseDTO> getAllRepositoryData() {
         log.info("RequestService: Initiating data extraction from database");
 
-        // 1. Fetch all TeamParticipation records
+        // Fetch all TeamParticipation records
         List<TeamParticipation> participations = teamParticipationRepository.findAll();
 
-        // 2. Map and assemble the data into ClientResponseDTOs
+        // Map and assemble the data into ClientResponseDTOs
         List<ClientResponseDTO> responseDTOs = participations.stream()
                 .map(participation -> {
                     List<Student> students = studentRepository.findAllByTeam(participation);
@@ -161,7 +171,7 @@ public List<ClientResponseDTO> getAllRepositoryData() {
                 })
                 .toList();
 
-        log.info("RequestService: Extracted {} team participation records.", responseDTOs.size());
+        log.info("RequestService: Extracted {} team participation records from the database.", responseDTOs.size());
         return responseDTOs;
     }
 }

src/main/java/de/tum/cit/aet/dataProcessing/web/RequestResource.java

@@ -56,7 +56,6 @@ public ResponseEntity<List<ClientResponseDTO>> fetchData(
         }
 
         requestService.fetchAnalyzeAndSaveRepositories(credentials);
-        log.info("Successfully fetched, analyzed, and saved repository data");
         List<ClientResponseDTO> clientResponseDTOS = requestService.getAllRepositoryData();
         return ResponseEntity.ok(clientResponseDTOS);
     }

src/main/java/de/tum/cit/aet/repositoryProcessing/domain/Student.java

@@ -37,7 +37,7 @@ public class Student {
     @Column(name = "lines_added")
     private Integer linesAdded;
 
-    @Column(name  = "lines_deleted")
+    @Column(name = "lines_deleted")
     private Integer linesDeleted;
 
     @Column(name = "lines_changed")

src/main/java/de/tum/cit/aet/repositoryProcessing/dto/ClientResponseDTO.java

@@ -4,6 +4,16 @@
 
 import java.util.List;
 
+/**
+ * DTO representing the response sent to clients.
+ *
+ * @param tutor           The name of the tutor associated with the team.
+ * @param teamId          The unique identifier of the team.
+ * @param teamName        The full name of the team.
+ * @param shortName       The short name or abbreviation of the team.
+ * @param submissionCount The number of submissions made by the team.
+ * @param students        A list of StudentAnalysisDTO representing individual student analyses within the team.
+ */
 @JsonInclude(JsonInclude.Include.NON_NULL)
 public record ClientResponseDTO(
         String tutor,

src/main/java/de/tum/cit/aet/repositoryProcessing/dto/StudentAnalysisDTO.java

@@ -2,12 +2,21 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 
+/**
+ * DTO representing the analysis of a student's contributions which will be sent to the client
+ *
+ * @param name         The name of the student.
+ * @param commitCount  The number of commits made by the student.
+ * @param linesAdded   The number of lines added by the student.
+ * @param linesDeleted The number of lines deleted by the student.
+ * @param linesChanged The total number of lines changed by the student.
+ */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public record StudentAnalysisDTO(
         String name,
         Integer commitCount,
         Integer linesAdded,
         Integer linesDeleted,
         Integer linesChanged
-){
+) {
 }

src/main/java/de/tum/cit/aet/repositoryProcessing/dto/VCSLogDTO.java

@@ -2,6 +2,13 @@
 
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 
+/**
+ * DTO for a VCS Log entry.
+ *
+ * @param email                The email of the committer.
+ * @param repositoryActionType The type of action performed in the repository.
+ * @param commitHash           The hash of the commit.
+ */
 @JsonIgnoreProperties(ignoreUnknown = true)
 public record VCSLogDTO(
         String email,

src/main/java/de/tum/cit/aet/repositoryProcessing/service/ArtemisClientService.java

@@ -189,7 +189,7 @@ public String getVcsAccessToken(String serverUrl, String jwtToken, Long particip
      * @param serverUrl       The Artemis server URL
      * @param jwtToken        The JWT token for authentication
      * @param participationId The ID of the participation
-     * @return List of VCS log DTOs filtered for WRITE actions
+     * @return List of VCS log DTOs filtered for commits
      */
     public List<VCSLogDTO> fetchVCSAccessLog(String serverUrl, String jwtToken, Long participationId) {
         log.info("Fetching VCS access log for participation ID: {}", participationId);
@@ -208,6 +208,7 @@ public List<VCSLogDTO> fetchVCSAccessLog(String serverUrl, String jwtToken, Long
                     .body(new ParameterizedTypeReference<>() {
                     });
 
+            // Filter the fetched logs to only include "WRITE" actions, indicating a commit
             if (vcsLogs != null) {
                 vcsLogs = vcsLogs.stream()
                         .filter(entry -> "WRITE".equals(entry.repositoryActionType()))