From dc6d0ded6e0266af343357961d63f329b7db21eb Mon Sep 17 00:00:00 2001
From: Martin Weise <martin.weise@tuwien.ac.at>
Date: Wed, 29 Sep 2021 15:47:32 +0200
Subject: [PATCH] added some comments

Former-commit-id: 4ed9f348d2c8a6360c09049df07d582088c8118e
---
 .../java/at/tuwien/service/FileService.java   | 48 +++++++++++++++++++
 .../at/tuwien/service/MetadataService.java    | 32 +++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/fda-citation-service/services/src/main/java/at/tuwien/service/FileService.java b/fda-citation-service/services/src/main/java/at/tuwien/service/FileService.java
index 659b8d125d..36e3259214 100644
--- a/fda-citation-service/services/src/main/java/at/tuwien/service/FileService.java
+++ b/fda-citation-service/services/src/main/java/at/tuwien/service/FileService.java
@@ -11,14 +11,62 @@ import java.util.List;
 @Service
 public interface FileService {
 
+    /**
+     * Upload a new file to a remote server for a given database-table id pair and metadata
+     *
+     * @param databaseId The database-table id paid
+     * @param tableId    The database-table id pair
+     * @param data       The metadata
+     * @param resource   The file
+     * @return The new file
+     * @throws ZenodoAuthenticationException     Token invalid
+     * @throws ZenodoApiException                Something other went wrong
+     * @throws ZenodoNotFoundException           The deposit id was not found on the remote server
+     * @throws ZenodoFileTooLargeException       The file exceeds the capabilities
+     * @throws MetadataDatabaseNotFoundException The deposit was not found on the metadata database
+     */
     FileResponseDto createResource(Long databaseId, Long tableId, FileUploadDto data, File resource)
             throws ZenodoAuthenticationException, ZenodoApiException, ZenodoNotFoundException,
             ZenodoFileTooLargeException, MetadataDatabaseNotFoundException;
 
+    /**
+     * List all files known to a deposit number (through the database-table id pair)
+     *
+     * @param databaseId The database-table id pair
+     * @param tableId    The database-table id pair
+     * @return The list of files
+     * @throws ZenodoAuthenticationException     Token invalid
+     * @throws ZenodoApiException                Something other went wrong
+     * @throws ZenodoNotFoundException           The deposit id was not found on the remote server
+     * @throws MetadataDatabaseNotFoundException The deposit was not found on the metadata database
+     */
     List<FileResponseDto> listResources(Long databaseId, Long tableId) throws MetadataDatabaseNotFoundException, ZenodoAuthenticationException, ZenodoNotFoundException, ZenodoApiException;
 
+    /**
+     * Find a file for a deposit (through the database-table id pair) by id
+     *
+     * @param databaseId The database-table id pair
+     * @param tableId    The database-table id pair
+     * @param fileId     The file id
+     * @return The file
+     * @throws MetadataDatabaseNotFoundException The deposit was not found on the metadata database
+     * @throws ZenodoAuthenticationException     Token invalid
+     * @throws ZenodoNotFoundException           The deposit id was not found on the remote server
+     * @throws ZenodoApiException                Something other went wrong
+     */
     FileResponseDto findResource(Long databaseId, Long tableId, String fileId) throws MetadataDatabaseNotFoundException, ZenodoAuthenticationException, ZenodoNotFoundException, ZenodoApiException;
 
+    /**
+     * Delete a file based on the database-table id pair by id
+     *
+     * @param databaseId The database-table id pair
+     * @param tableId    The database-table id pair
+     * @param fileId     The file id
+     * @throws MetadataDatabaseNotFoundException The deposit was not found on the metadata database
+     * @throws ZenodoAuthenticationException     Token invalid
+     * @throws ZenodoNotFoundException           The deposit id was not found on the remote server
+     * @throws ZenodoApiException                Something other went wrong
+     */
     void deleteResource(Long databaseId, Long tableId, String fileId)
             throws MetadataDatabaseNotFoundException, ZenodoAuthenticationException, ZenodoNotFoundException,
             ZenodoApiException;
diff --git a/fda-citation-service/services/src/main/java/at/tuwien/service/MetadataService.java b/fda-citation-service/services/src/main/java/at/tuwien/service/MetadataService.java
index b1102305cd..5d81bda10f 100644
--- a/fda-citation-service/services/src/main/java/at/tuwien/service/MetadataService.java
+++ b/fda-citation-service/services/src/main/java/at/tuwien/service/MetadataService.java
@@ -10,12 +10,44 @@ import java.util.List;
 
 @Service
 public interface MetadataService {
+
+    /**
+     * List all deposits (e.g. datasets) available
+     *
+     * @return The deposists
+     * @throws ZenodoAuthenticationException Token invalid
+     * @throws ZenodoApiException            Something other went wrong
+     */
     List<DepositResponseDto> listCitations() throws ZenodoAuthenticationException, ZenodoApiException;
 
+    /**
+     * Create a new deposit
+     *
+     * @return The created deposit
+     * @throws ZenodoAuthenticationException Token invalid
+     * @throws ZenodoApiException            Something other went wrong
+     */
     DepositChangeResponseDto storeCitation() throws ZenodoAuthenticationException, ZenodoApiException;
 
+    /**
+     * Update a deposit with new metadata for a given id
+     *
+     * @param id   The id
+     * @param data The new metadata
+     * @return The updated deposit
+     * @throws ZenodoAuthenticationException Token invalid
+     * @throws ZenodoApiException            Something other went wrong
+     * @throws ZenodoNotFoundException       The deposit id was not found on the remote server
+     */
     DepositChangeResponseDto updateCitation(Long id, DepositChangeRequestDto data) throws ZenodoAuthenticationException,
             ZenodoApiException, ZenodoNotFoundException;
 
+    /**
+     * Delete a deposit from a given id
+     *
+     * @param id The id
+     * @throws ZenodoAuthenticationException Token invalid
+     * @throws ZenodoApiException            Something other went wrong
+     */
     void deleteCitation(Long id) throws ZenodoAuthenticationException, ZenodoApiException;
 }
-- 
GitLab