more javadoc

src/main/java/de/tum/cit/aet/artemis/core/config/Constants.java

@@ -377,14 +377,23 @@ public final class Constants {
     public static final int PUSH_NOTIFICATION_VERSION = 1;
 
     /**
-     * sharing configution
+     * sharing configution resource path for sharing config request
      */
     public static final String SHARINGCONFIG_RESOURCE_PATH = "/sharing/config";
 
+    /**
+     * sharing configution resource path for sharing config import request
+     */
     public static final String SHARINGIMPORT_RESOURCE_PATH = "/sharing/import";
 
+    /**
+     * sharing configution resource path for sharing config export request
+     */
     public static final String SHARINGEXPORT_RESOURCE_PATH = "/sharing/export";
 
+    /**
+     * sharing configution resource path for rest request, iff sharing profile is enabled
+     */
     public static final String SHARINGCONFIG_RESOURCE_IS_ENABLED = SHARINGCONFIG_RESOURCE_PATH + "/is-enabled";
 
     /**

src/main/java/de/tum/cit/aet/artemis/core/config/SecurityConfiguration.java

@@ -208,7 +208,7 @@ public SecurityFilterChain filterChain(HttpSecurity http, SecurityProblemSupport
                     .requestMatchers("/websocket/**").permitAll()
                     .requestMatchers("/.well-known/jwks.json").permitAll()
                     .requestMatchers("/.well-known/assetlinks.json").permitAll()
-                    // sharing is protected by explicit security tokens
+                    // sharing is protected by explicit security tokens, thus we can permitAll here
                     .requestMatchers("/api/sharing/**").permitAll()
                     // Prometheus endpoint protected by IP address.
                     .requestMatchers("/management/prometheus/**").access((authentication, context) -> new AuthorizationDecision(monitoringIpAddresses.contains(context.getRequest().getRemoteAddr())));

src/main/java/de/tum/cit/aet/artemis/core/dto/SharingInfoDTO.java

@@ -1,47 +1,102 @@
 package de.tum.cit.aet.artemis.core.dto;
 
+import java.util.Objects;
+
 import org.springframework.context.annotation.Profile;
 
+/**
+ * the sharing info to request an specific exercise from the sharing platform.
+ */
 @Profile("sharing")
 public class SharingInfoDTO {
 
+    /**
+     * the (random) basket Token
+     */
     private String basketToken;
 
+    /**
+     * the callback URL for the basket request
+     */
     private String returnURL;
 
+    /**
+     * the base URL for the basket request
+     */
     private String apiBaseURL;
 
+    /**
+     * the index of the request exercise
+     */
     private int exercisePosition;
 
+    /**
+     * the callback URL for the basket request
+     */
     public String getReturnURL() {
         return returnURL;
     }
 
+    /**
+     * sets the callback URL for the basket request
+     */
     public void setReturnURL(String returnURL) {
         this.returnURL = returnURL;
     }
 
+    /**
+     * the base URL for the basket request
+     */
     public String getApiBaseURL() {
         return apiBaseURL;
     }
 
+    /**
+     * sets the base URL for the basket request
+     */
     public void setApiBaseURL(String apiBaseURL) {
         this.apiBaseURL = apiBaseURL;
     }
 
+    /**
+     * the (random) basket Token
+     */
     public String getBasketToken() {
         return basketToken;
     }
 
+    /**
+     * sets the basket Token
+     */
     public void setBasketToken(String basketToken) {
         this.basketToken = basketToken;
     }
 
+    /**
+     * the index of the request exercise
+     */
     public int getExercisePosition() {
         return exercisePosition;
     }
 
+    /**
+     * sets the index of the request exercise
+     */
     public void setExercisePosition(int exercisePosition) {
         this.exercisePosition = exercisePosition;
     }
+
+    @Override
+    public boolean equals(Object o) {
+        if (o == null || getClass() != o.getClass())
+            return false;
+        SharingInfoDTO that = (SharingInfoDTO) o;
+        return exercisePosition == that.exercisePosition && Objects.equals(basketToken, that.basketToken) && Objects.equals(returnURL, that.returnURL)
+                && Objects.equals(apiBaseURL, that.apiBaseURL);
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(basketToken, returnURL, apiBaseURL, exercisePosition);
+    }
 }

src/main/java/de/tum/cit/aet/artemis/core/service/ProfileService.java

@@ -131,6 +131,11 @@ public boolean isProductionActive() {
         return isProfileActive(JHipsterConstants.SPRING_PROFILE_PRODUCTION);
     }
 
+    /**
+     * Checks if the sharing profile is active
+     *
+     * @return true if the sharing profile is active, false otherwise
+     */
     public boolean isSharing() {
         return isProfileActive("sharing");
     }

src/main/java/de/tum/cit/aet/artemis/core/web/SharingSupportResource.java

@@ -21,30 +21,43 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
-import de.tum.cit.aet.artemis.exercise.service.sharing.SharingPluginService;
+import de.tum.cit.aet.artemis.exercise.service.sharing.SharingConnectorService;
 
 /**
- * REST controller for Supporting Import and Export from/to Sharing Platform.
+ * REST controller for the exchange of configuration data between artemis and the sharing platform.
  */
 @Validated
 @RestController
 @RequestMapping("/api")
 @Profile("sharing")
 public class SharingSupportResource {
 
+    /**
+     * the logger
+     */
     private final Logger log = LoggerFactory.getLogger(SharingSupportResource.class);
 
-    private final SharingPluginService sharingPluginService;
+    /**
+     * the sharing plugin service
+     */
+    private final SharingConnectorService sharingPluginService;
 
+    /**
+     * constructor
+     *
+     * @param sharingPluginService
+     */
     @SuppressWarnings("unused")
-    public SharingSupportResource(SharingPluginService sharingPluginService) {
+    public SharingSupportResource(SharingConnectorService sharingPluginService) {
         this.sharingPluginService = sharingPluginService;
     }
 
     /**
      * Returns Sharing Plugin configuration to be used in context with Artemis.
+     * This configuration is requested by the sharing platform on a regular basis.
+     * It is secured by the common secret api key token transferred by Authorization header.
      *
-     * @param sharingApiKey    the common secret api key token
+     * @param sharingApiKey    the common secret api key token (transfered by Authorization header).
      * @param apiBaseUrl       the base url of the sharing application api (for callbacks)
      * @param installationName a descriptive name of the sharing application
      *
@@ -53,7 +66,6 @@ public SharingSupportResource(SharingPluginService sharingPluginService) {
      *
      */
     @GetMapping(SHARINGCONFIG_RESOURCE_PATH)
-    @SuppressWarnings("unused")
     public ResponseEntity<SharingPluginConfig> getConfig(@RequestHeader("Authorization") Optional<String> sharingApiKey, @RequestParam String apiBaseUrl,
             @RequestParam String installationName) {
         if (sharingApiKey.isPresent() && sharingPluginService.validate(sharingApiKey.get())) {

src/main/java/de/tum/cit/aet/artemis/exercise/service/sharing/ProgrammingExerciseImportFromSharingService.java

@@ -17,18 +17,40 @@
 import de.tum.cit.aet.artemis.sharing.SharingMultipartZipFile;
 import de.tum.cit.aet.artemis.sharing.SharingSetupInfo;
 
+/**
+ * Service for importing programming exercises from the sharing service.
+ */
 @Service
 @Profile("sharing")
 public class ProgrammingExerciseImportFromSharingService {
 
+    /**
+     * the logger
+     */
     private final Logger log = LoggerFactory.getLogger(ProgrammingExerciseImportFromSharingService.class);
 
+    /**
+     * the import from file service (because this service strongly relies in the file import format.
+     */
     private final ProgrammingExerciseImportFromFileService programmingExerciseImportFromFileService;
 
-    private final de.tum.cit.aet.artemis.sharing.ExerciseSharingService exerciseSharingService;
+    /**
+     * the general exercise sharing service.
+     */
+    private final ExerciseSharingService exerciseSharingService;
 
+    /**
+     * the user repository
+     */
     private final UserRepository userRepository;
 
+    /**
+     * constructor for spring initialization
+     *
+     * @param programmingExerciseImportFromFileService import from file services
+     * @param exerciseSharingService                   exercise sharing service
+     * @param userRepository                           user repository
+     */
     public ProgrammingExerciseImportFromSharingService(ProgrammingExerciseImportFromFileService programmingExerciseImportFromFileService,
             ExerciseSharingService exerciseSharingService, UserRepository userRepository) {
         this.programmingExerciseImportFromFileService = programmingExerciseImportFromFileService;

src/main/java/de/tum/cit/aet/artemis/exercise/service/sharing/SharingPluginService.java → src/main/java/de/tum/cit/aet/artemis/exercise/service/sharing/SharingConnectorService.java

@@ -23,12 +23,11 @@
  *
  * @see <a href="https://sharing-codeability.uibk.ac.at/sharing/codeability-sharing-platform/-/wikis/technical/Plugin-Interface">Plugin Tutorial</a>
  */
-@SuppressWarnings("unused")
 @Service
 @Profile("sharing")
-public class SharingPluginService {
+public class SharingConnectorService {
 
-    private final Logger log = LoggerFactory.getLogger(SharingPluginService.class);
+    private final Logger log = LoggerFactory.getLogger(SharingConnectorService.class);
 
     /**
      * Base url for callbacks
@@ -40,21 +39,37 @@ public class SharingPluginService {
      */
     private String installationName = null;
 
+    /**
+     * the shared secret api key
+     */
     @Value("${artemis.sharing.api-key:#{null}}")
     private String sharingApiKey;
 
+    /**
+     * the url of the sharing platform.
+     * Only needed for initial trigger an configuration exchange during startup.
+     */
     @Value("${artemis.sharing.server-url:#{null}}")
     private String sharingUrl;
 
+    /**
+     * installation name for Sharing Platform
+     */
     public String getInstallationName() {
         return installationName;
     }
 
+    /**
+     * profile service
+     */
     private final ProfileService profileService;
 
+    /**
+     * rest template for connector request
+     */
     private final RestTemplate restTemplate;
 
-    public SharingPluginService(ProfileService profileService, RestTemplate restTemplate) {
+    public SharingConnectorService(ProfileService profileService, RestTemplate restTemplate) {
         this.profileService = profileService;
         this.restTemplate = restTemplate;
     }
@@ -117,7 +132,7 @@ public SharingPluginConfig getPluginConfig(URL apiBaseUrl, String installationNa
     }
 
     /**
-     * Method used to validate the given authorization apiKey from Sharing
+     * Method used to validate the given authorizaion apiKey from Sharing
      *
      * @param apiKey the Key to validate
      * @return true if valid, false otherwise
@@ -132,13 +147,20 @@ public boolean validate(String apiKey) {
         return sharingApiKey.equals(apiKey);
     }
 
+    /**
+     * At (spring) application startup, we request a reinitialization of the sharing platform .
+     * It starts a background thread in order not to block application startup.
+     */
     @EventListener(ApplicationReadyEvent.class)
     public void triggerSharingReinitAfterApplicationStart() {
         // we have to trigger sharing plattform reinitialization asynchronously,
         // because otherwise the main thread is blocked!
         Executors.newFixedThreadPool(1).execute(this::triggerReinit);
     }
 
+    /**
+     * request a reinitialization of the sharing platform
+     */
     public void triggerReinit() {
         if (sharingUrl != null) {
             log.info("Requesting reinitialization from Sharing Platform");

src/main/java/de/tum/cit/aet/artemis/exercise/service/sharing/SharingException.java

@@ -2,6 +2,9 @@
 
 import org.springframework.context.annotation.Profile;
 
+/**
+ * Sharing Exception during import or export to sharing platform.
+ */
 @Profile("sharing")
 public class SharingException extends Exception {