From ed009e21bcdaa107223160d349a390c92dce386a Mon Sep 17 00:00:00 2001 From: Jan van Mansum Date: Wed, 11 Dec 2024 14:19:26 +0100 Subject: [PATCH] Added Javadocs to document key interfaces. --- .../bagprocessor/BagProcessorFactory.java | 12 +++++ .../core/dansbag/DansBagMappingService.java | 47 +++++++++++++++++++ .../dansbag/DansDepositSupportFactory.java | 10 ++++ 3 files changed, 69 insertions(+) diff --git a/src/main/java/nl/knaw/dans/dvingest/core/bagprocessor/BagProcessorFactory.java b/src/main/java/nl/knaw/dans/dvingest/core/bagprocessor/BagProcessorFactory.java index 8c1b76e..396c29d 100644 --- a/src/main/java/nl/knaw/dans/dvingest/core/bagprocessor/BagProcessorFactory.java +++ b/src/main/java/nl/knaw/dans/dvingest/core/bagprocessor/BagProcessorFactory.java @@ -21,8 +21,20 @@ import java.io.IOException; import java.util.UUID; +/** + * Factory for creating BagProcessors. + */ public interface BagProcessorFactory { + /** + * Create a BagProcessor for the given deposit. + * + * @param depositId the deposit id + * @param bag the bag + * @return the BagProcessor + * @throws ConfigurationException if the Yaml files in the bag are not valid + * @throws IOException if there was a problem readin the bag files + */ BagProcessor createBagProcessor(UUID depositId, DataverseIngestBag bag) throws ConfigurationException, IOException; } diff --git a/src/main/java/nl/knaw/dans/dvingest/core/dansbag/DansBagMappingService.java b/src/main/java/nl/knaw/dans/dvingest/core/dansbag/DansBagMappingService.java index b55e326..bf274a4 100644 --- a/src/main/java/nl/knaw/dans/dvingest/core/dansbag/DansBagMappingService.java +++ b/src/main/java/nl/knaw/dans/dvingest/core/dansbag/DansBagMappingService.java @@ -26,16 +26,63 @@ import java.io.IOException; import java.nio.file.Path; +/** + * Service for mapping a DANS deposit to a standard Dataverse ingest deposit. A DANS deposit has only one bag, which must conform to the DANS BagIt Profile. + */ public interface DansBagMappingService { + /** + * Returns the DOI of the dataset that needs to be updated. If the deposit is to create a new dataset, this method returns null. + * + * @param depositDir the deposit directory + * @return the DOI of the dataset that needs to be updated, or null if the deposit is to create a new dataset + * @throws IOException if there was an error reading the deposit or calling Dataverse + * @throws DataverseException if a call to Dataverse failed + */ String getUpdatesDataset(Path depositDir) throws IOException, DataverseException; + /** + * Reads the DANS deposit from the given directory into a {@link DansBagDeposit} object. + * + * @param depositDir the deposit directory + * @return the DANS deposit object + * @throws InvalidDepositException if the deposit is invalid + */ DansBagDeposit readDansDeposit(Path depositDir) throws InvalidDepositException; + /** + * Maps the metadata from the DANS deposit to the new dataset level metadata for the dataset. For some parts the new metadata depends on the current metadata of the dataset. That is why the + * current metadata is also given as input. If the deposit is to create a new dataset, the current metadata is null. + * + * @param dansDeposit the DANS deposit + * @param currentMetadata the current metadata of the dataset + * @return the new dataset level metadata + */ Dataset getDatasetMetadataFromDansDeposit(DansBagDeposit dansDeposit, DatasetVersion currentMetadata); + /** + * Maps file information in the DANS bag to edit actions for the files in the dataset. The edit actions are used to update the files in the dataset. + * + * @param dansDeposit the DANS deposit + * @param updatesDataset the DOI of the dataset that needs to be updated, or null if the deposit is to create a new dataset + * @return the edit actions for the files in the dataset + */ EditFiles getEditFilesFromDansDeposit(DansBagDeposit dansDeposit, String updatesDataset); + /** + * Maps the permissions in the DANS deposit to edit actions for the permissions of the dataset. The edit actions are used to update the permissions of the dataset. + * + * @param dansDeposit the DANS deposit + * @param updatesDataset the DOI of the dataset that needs to be updated, or null if the deposit is to create a new dataset + * @return the edit actions for the permissions of the dataset + */ EditPermissions getEditPermissionsFromDansDeposit(DansBagDeposit dansDeposit, String updatesDataset); + /** + * Packages the original metadata of the DANS bag into a ZIP file and returns the local path to the ZIP file. + * + * @param dansDeposit the DANS deposit + * @return the local path to the ZIP file + * @throws IOException if there was an error reading the deposit or writing the ZIP file + */ String packageOriginalMetadata(DansBagDeposit dansDeposit) throws IOException; } diff --git a/src/main/java/nl/knaw/dans/dvingest/core/dansbag/DansDepositSupportFactory.java b/src/main/java/nl/knaw/dans/dvingest/core/dansbag/DansDepositSupportFactory.java index 7c81b72..95f06e7 100644 --- a/src/main/java/nl/knaw/dans/dvingest/core/dansbag/DansDepositSupportFactory.java +++ b/src/main/java/nl/knaw/dans/dvingest/core/dansbag/DansDepositSupportFactory.java @@ -18,8 +18,18 @@ import nl.knaw.dans.dvingest.core.DataverseIngestDeposit; import nl.knaw.dans.dvingest.core.Deposit; +/** + * Factory for creating DansDepositSupport objects. + */ public interface DansDepositSupportFactory { + /** + * Create a DansDepositSupport object for the given deposit. The object implements the {@link Deposit} interface, implementing the appropriate methods and forwarding the others to call the + * original deposit. If DANS deposit support is disabled, the deposit is returned as is. + * + * @param deposit the deposit + * @return the DansDepositSupport object + */ Deposit addDansDepositSupportIfEnabled(DataverseIngestDeposit deposit); }