[CST-18016] Improved doc

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/contributor/AbstractJsonPathMetadataProcessor.java

@@ -18,10 +18,42 @@
 
 
 /**
+ * An abstract implementation of {@link JsonPathMetadataProcessor} that processes JSON data
+ * using a JSONPath expression. This class provides a base structure for extracting values
+ * from a JSON object while allowing subclasses to define specific behaviors.
+ *
+ * The extraction process:
+ * <ol>
+ *     <li>Converts a JSON string into a {@link JsonNode} object.</li>
+ *     <li>Retrieves a sub-node based on the JSONPath expression returned by {@link #getPath()}.</li>
+ *     <li>Extracts values from the node and processes them using {@link #getStringValue(JsonNode)}.</li>
+ *     <li>Returns a collection of extracted values.</li>
+ * </ol>
+ *
+ * Subclasses must implement:
+ * <ul>
+ *     <li>{@link #getStringValue(JsonNode)} - Defines how values are extracted from a JSON node.</li>
+ *     <li>{@link #getLogger()} - Provides a logger instance for error handling.</li>
+ *     <li>{@link #getPath()} - Specifies the JSONPath used to extract data.</li>
+ * </ul>
+ *
+ *
+ * @see JsonPathMetadataProcessor
+ * @see JsonNode
+ * @see ObjectMapper
+ * @see Logger
+ *
  * @author Adamo Fapohunda (adamo.fapohunda at 4science.com)
- **/
+ */
 public abstract class AbstractJsonPathMetadataProcessor implements JsonPathMetadataProcessor {
 
+    /**
+     * Extracts metadata from a JSON string using a predefined JSONPath.
+     * The extracted values are processed and returned as a collection of strings.
+     *
+     * @param json The JSON string to process.
+     * @return A collection of extracted string values.
+     */
     @Override
     public Collection<String> processMetadata(String json) {
         Collection<String> values = new ArrayList<>();
@@ -43,12 +75,37 @@ public Collection<String> processMetadata(String json) {
         return values;
     }
 
+    /**
+     * Extracts a string representation of the value from a {@link JsonNode}.
+     * The implementation of this method must be provided by subclasses.
+     *
+     * @param node The JSON node from which to extract the value.
+     * @return A string representation of the value.
+     */
     protected abstract String getStringValue(JsonNode node);
 
+    /**
+     * Provides the logger for logging errors and messages.
+     * The implementation of this method must be provided by subclasses.
+     *
+     * @return A {@link Logger} instance.
+     */
     protected abstract Logger getLogger();
 
+    /**
+     * Returns the JSONPath expression used for extracting values from JSON.
+     * The implementation of this method must be provided by subclasses.
+     *
+     * @return A string representing the JSONPath expression.
+     */
     protected abstract String getPath();
 
+    /**
+     * Converts a JSON string into a {@link JsonNode} object.
+     *
+     * @param json The JSON string to be parsed.
+     * @return A {@link JsonNode} representation of the JSON string, or {@code null} if parsing fails.
+     */
     private JsonNode convertStringJsonToJsonNode(String json) {
         ObjectMapper mapper = new ObjectMapper();
         JsonNode body = null;

dspace-api/src/main/java/org/dspace/importer/external/metadatamapping/contributor/RegexReplacingJsonPathMetadataProcessor.java

@@ -0,0 +1,99 @@
+/**
+ * The contents of this file are subject to the license and copyright
+ * detailed in the LICENSE and NOTICE files at the root of the source
+ * tree and available online at
+ *
+ * http://www.dspace.org/license/
+ */
+package org.dspace.importer.external.metadatamapping.contributor;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.Logger;
+
+/**
+ * A generic JSON metadata processor that extracts a string value from a JSON node
+ * using a specified JSONPath and applies a regex-based replacement.
+ *
+ * This class extends {@link AbstractJsonPathMetadataProcessor} and provides functionality
+ * to replace a matching regex pattern in the extracted text with a given replacement value.
+ *
+ * @author Adamo Fapohunda (adamo.fapohunda at 4science.com)
+ * @see AbstractJsonPathMetadataProcessor
+ * @see JsonPathMetadataProcessor
+ */
+public class RegexReplacingJsonPathMetadataProcessor extends AbstractJsonPathMetadataProcessor {
+
+    private static final Logger log = LogManager.getLogger(RegexReplacingJsonPathMetadataProcessor.class);
+
+    private String path;
+    private String regexPattern;
+    private String replacement;
+
+
+    /**
+     * Extracts the string value from the given JSON node and applies regex-based replacement.
+     *
+     * @param node The JSON node from which to extract the value.
+     * @return The transformed string after applying the regex replacement.
+     * @throws IllegalArgumentException if the node is null or does not contain a text value.
+     */
+    @Override
+    protected String getStringValue(JsonNode node) {
+        if (node == null || !node.isTextual()) {
+            throw new IllegalArgumentException("Input must be a non-null JsonNode containing a text value");
+        }
+        String idStr = node.asText();
+        if (regexPattern == null || regexPattern.isEmpty() || replacement == null) {
+            return idStr;
+        }
+        return idStr.replaceAll(regexPattern, replacement);
+    }
+
+    /**
+     * Provides the logger instance for error handling.
+     *
+     * @return A {@link Logger} instance.
+     */
+    @Override
+    protected Logger getLogger() {
+        return log;
+    }
+
+    /**
+     * Returns the JSONPath expression used to locate the value in the JSON structure.
+     *
+     * @return The JSONPath string.
+     */
+    @Override
+    protected String getPath() {
+        return path;
+    }
+
+    /**
+     * Sets the JSONPath expression used for extraction.
+     *
+     * @param path The JSONPath string.
+     */
+    public void setPath(String path) {
+        this.path = path;
+    }
+
+    /**
+     * Sets the regex pattern to be replaced in the extracted string.
+     *
+     * @param regexPattern The regular expression pattern.
+     */
+    public void setRegexPattern(String regexPattern) {
+        this.regexPattern = regexPattern;
+    }
+
+    /**
+     * Sets the replacement string that will replace occurrences of the regex pattern.
+     *
+     * @param replacement The replacement string.
+     */
+    public void setReplacement(String replacement) {
+        this.replacement = replacement;
+    }
+}

dspace-api/src/main/java/org/dspace/importer/external/openalex/metadatamapping/OpenAlexDateMetadataProcessor.java

@@ -17,14 +17,38 @@
 import org.dspace.importer.external.metadatamapping.contributor.AbstractJsonPathMetadataProcessor;
 
 /**
+ * A metadata processor that extracts and validates date values from JSON data.
+ * This processor retrieves a date string from a specified JSON path and ensures
+ * that it is correctly formatted according to the ISO 8601 date standard.
+ *
+ * <p>Example JSON:
+ * <pre>
+ * {
+ *   "published_date": "2023-05-10"
+ * }
+ * </pre>
+ *
+ * If the `path` is set to `"/published_date"`, the extracted value will be `"2023-05-10"`.
+ *
+ * <p>This class extends {@link AbstractJsonPathMetadataProcessor}, which handles JSON parsing and path extraction.
+ *
  * @author Adamo Fapohunda (adamo.fapohunda at 4science.com)
- **/
+ */
 public class OpenAlexDateMetadataProcessor extends AbstractJsonPathMetadataProcessor {
 
     private static final Logger log = LogManager.getLogger(OpenAlexDateMetadataProcessor.class);
 
     private String path;
 
+
+    /**
+     * Extracts and validates a date value from a JSON node.
+     * The extracted value must conform to the ISO 8601 format (YYYY-MM-DD).
+     *
+     * @param node The JSON node containing the date as a text value.
+     * @return The parsed date as a string in ISO 8601 format.
+     * @throws IllegalArgumentException If the node is null, not textual, or does not contain a valid date.
+     */
     @Override
     protected String getStringValue(JsonNode node) {
 
@@ -41,16 +65,31 @@ protected String getStringValue(JsonNode node) {
         }
     }
 
+    /**
+     * Provides the logger instance for error reporting.
+     *
+     * @return The {@link Logger} instance.
+     */
     @Override
     protected Logger getLogger() {
         return log;
     }
 
+    /**
+     * Retrieves the JSON path expression used to extract the date value.
+     *
+     * @return The JSONPath expression as a string.
+     */
     @Override
     protected String getPath() {
         return path;
     }
 
+    /**
+     * Sets the JSON path from which the date value should be extracted.
+     *
+     * @param path The JSONPath expression specifying the location of the date in the JSON structure.
+     */
     public void setPath(String path) {
         this.path = path;
     }

dspace-api/src/main/java/org/dspace/importer/external/openalex/metadatamapping/OpenAlexPersonFieldMapping.java

@@ -13,6 +13,10 @@
 import org.dspace.importer.external.metadatamapping.AbstractMetadataFieldMapping;
 
 /**
+ * An implementation of {@link AbstractMetadataFieldMapping} responsible for
+ * defining the mapping of the OpenAlex Author metadatum fields on the DSpace
+ * Person metadatum fields
+ *
  * @author Adamo Fapohunda (adamo.fapohunda at 4science.com)
  **/
 public class OpenAlexPersonFieldMapping extends AbstractMetadataFieldMapping {