Merge remote-tracking branch 'origin/sh/#872-storage-documentation' into sh/#872-storage-documentation

Author: SimonHuette

CHANGELOG.md

@@ -14,7 +14,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 - Changing from comparing strings to comparing uuids in `EntitySource.findFirstEntityByUuid` [#829](https://github.com/ie3-institute/PowerSystemDataModel/issues/829)
-
+- Adding JavaDoc to `EntitySource.safeMapGet` [#828](https://github.com/ie3-institute/PowerSystemDataModel/issues/828)
+- Abstracting some methods in `ValidationUtils` [#852](https://github.com/ie3-institute/PowerSystemDataModel/issues/852)
 
 ## [4.1.0] - 2023-11-02
 

Jenkinsfile

@@ -451,7 +451,6 @@ def constantBranchesProps() {
     [
       string(defaultValue: '', description: '', name: 'deploy', trim: true)
     ]),
-    [$class: 'RebuildSettings', autoRebuild: false, rebuildDisabled: false],
     [$class: 'ThrottleJobProperty', categories: [], limitOneJobWithMatchingParams: false, maxConcurrentPerNode: 0, maxConcurrentTotal: 0, paramsToUseForLimit: '', throttleEnabled: true, throttleOption: 'project']
   ])
 }

build.gradle

@@ -4,8 +4,8 @@ plugins {
   id 'maven-publish'
   id 'signing'
   id 'pmd' // code check, working on source code
-  id 'com.diffplug.spotless' version '6.22.0' //code format
-  id 'com.github.spotbugs' version '5.2.3' // code check, working on byte code
+  id 'com.diffplug.spotless' version '6.23.2' //code format
+  id 'com.github.spotbugs' version '5.2.5' // code check, working on byte code
   id 'de.undercouch.download' version '5.5.0'
   id 'kr.motd.sphinx' version '2.10.1' // documentation generation
   id 'jacoco' // java code coverage plugin
@@ -17,7 +17,7 @@ ext {
   //version (changing these should be considered thoroughly!)
   javaVersion = JavaVersion.VERSION_17
   groovyVersion = "4.0"
-  groovyBinaryVersion = "4.0.15"
+  groovyBinaryVersion = "4.0.16"
   testcontainersVersion = '1.19.3'
 
   scriptsLocation = 'gradle' + File.separator + 'scripts' + File.separator //location of script plugins
@@ -93,7 +93,7 @@ dependencies {
   implementation 'com.couchbase.client:java-client:3.5.0'
   runtimeOnly 'org.postgresql:postgresql:42.7.0' // postgresql jdbc driver required during runtime
 
-  implementation 'commons-io:commons-io:2.15.0' // I/O functionalities
+  implementation 'commons-io:commons-io:2.15.1' // I/O functionalities
   implementation 'org.apache.commons:commons-compress:1.25.0' // I/O functionalities
   implementation 'org.apache.commons:commons-lang3:3.14.0'
 }

docs/readthedocs/requirements.txt

@@ -1,6 +1,6 @@
 commonmark==0.9.1
 recommonmark==0.7.1
 Sphinx==7.2.6
-sphinx-rtd-theme==1.3.0
+sphinx-rtd-theme==2.0.0
 myst-parser==2.0.0
 markdown-it-py==3.0.0

src/main/java/edu/ie3/datamodel/exceptions/DuplicateEntitiesException.java

@@ -0,0 +1,27 @@
+/*
+ * © 2023. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.exceptions;
+
+import edu.ie3.datamodel.models.UniqueEntity;
+import edu.ie3.datamodel.utils.ExceptionUtils;
+import java.util.Collection;
+
+public class DuplicateEntitiesException extends ValidationException {
+
+  protected DuplicateEntitiesException(String s) {
+    super(s);
+  }
+
+  protected DuplicateEntitiesException(String s, String entities) {
+    super(s + entities);
+  }
+
+  public DuplicateEntitiesException(String fieldName, Collection<? extends UniqueEntity> entities) {
+    this(
+        "The following entities have duplicate '" + fieldName + "': ",
+        ExceptionUtils.combine(entities));
+  }
+}

src/main/java/edu/ie3/datamodel/io/source/EntitySource.java

@@ -51,6 +51,17 @@ protected String buildSkippingMessage(
         + missingElementsString;
   }
 
+  /**
+   * Method for retrieving an element from a map. If the map doesn't contain the key an error
+   * message is build and returned instead.
+   *
+   * <p>Should not be used for other purposes than creating error messages.
+   *
+   * @param map with value
+   * @param key for the value
+   * @param mapName name of the map used for the error message
+   * @return either the value or an error message
+   */
   protected String safeMapGet(Map<String, String> map, String key, String mapName) {
     return Optional.ofNullable(map.get(key))
         .orElse(
@@ -83,7 +94,7 @@ protected <T extends UniqueEntity> Optional<T> findFirstEntityByUuid(
    * the provided fields to values mapping. The provided fields to values mapping needs to have one
    * and only one field with key {@link #TYPE} and a corresponding UUID value. If the type can be
    * found in the provided collection based on the UUID it is returned wrapped in a {@link Success}.
-   * Otherwise a {@link Failure} is returned and a warning is logged.
+   * Otherwise, a {@link Failure} is returned and a warning is logged.
    *
    * @param types a collection of types that should be used for searching
    * @param fieldsToAttributes the field name to value mapping incl. the key {@link #TYPE}

src/main/java/edu/ie3/datamodel/utils/ExceptionUtils.java

@@ -5,7 +5,10 @@
 */
 package edu.ie3.datamodel.utils;
 
+import edu.ie3.datamodel.models.UniqueEntity;
+import java.util.Collection;
 import java.util.List;
+import java.util.stream.Collectors;
 
 public class ExceptionUtils {
   private ExceptionUtils() {
@@ -24,4 +27,16 @@ public static String getMessages(List<? extends Exception> exceptions) {
         .reduce("", (a, b) -> a + "\n " + b)
         .replaceFirst("\n ", "");
   }
+
+  /**
+   * Combines multiple {@link UniqueEntity} into a string.
+   *
+   * @param entities to be combined
+   * @return a string
+   */
+  public static String combine(Collection<? extends UniqueEntity> entities) {
+    return "{"
+        + entities.stream().map(UniqueEntity::toString).collect(Collectors.joining(", "))
+        + "}";
+  }
 }

src/main/java/edu/ie3/datamodel/utils/validation/GridContainerValidationUtils.java

@@ -5,10 +5,8 @@
 */
 package edu.ie3.datamodel.utils.validation;
 
-import edu.ie3.datamodel.exceptions.InvalidEntityException;
-import edu.ie3.datamodel.exceptions.InvalidGridException;
-import edu.ie3.datamodel.exceptions.UnsafeEntityException;
-import edu.ie3.datamodel.exceptions.ValidationException;
+import edu.ie3.datamodel.exceptions.*;
+import edu.ie3.datamodel.models.UniqueEntity;
 import edu.ie3.datamodel.models.input.AssetInput;
 import edu.ie3.datamodel.models.input.MeasurementUnitInput;
 import edu.ie3.datamodel.models.input.NodeInput;
@@ -24,14 +22,6 @@
 
 public class GridContainerValidationUtils extends ValidationUtils {
 
-  private static String duplicateUuidsString(String simpleName, Optional<String> exceptionString) {
-    return "The provided entities in '"
-        + simpleName
-        + "' contains duplicate UUIDs. "
-        + "This is not allowed!\nDuplicated uuids:\n\n"
-        + exceptionString;
-  }
-
   /** Private Constructor as this class is not meant to be instantiated */
   private GridContainerValidationUtils() {
     throw new IllegalStateException("Don't try and instantiate a Utility class.");
@@ -52,18 +42,10 @@ private GridContainerValidationUtils() {
       return List.of(isNull);
     }
 
-    List<Try<Void, ? extends ValidationException>> exceptions = new ArrayList<>();
-
     /* sanity check to ensure distinct UUIDs */
-    Optional<String> exceptionString =
-        checkForDuplicateUuids(new HashSet<>(gridContainer.allEntitiesAsList()));
-    exceptions.add(
-        Try.ofVoid(
-            exceptionString.isPresent(),
-            () ->
-                new InvalidGridException(
-                    duplicateUuidsString(
-                        gridContainer.getClass().getSimpleName(), exceptionString))));
+    List<Try<Void, ? extends ValidationException>> exceptions =
+        new ArrayList<>(
+            checkForDuplicates(gridContainer.allEntitiesAsList(), UniqueEntity::getUuid));
 
     exceptions.addAll(checkRawGridElements(gridContainer.getRawGrid()));
     exceptions.addAll(
@@ -98,18 +80,10 @@ private GridContainerValidationUtils() {
       return List.of(isNull);
     }
 
-    List<Try<Void, ? extends ValidationException>> exceptions = new ArrayList<>();
-
     /* sanity check to ensure distinct UUIDs */
-    Optional<String> exceptionString =
-        checkForDuplicateUuids(new HashSet<>(rawGridElements.allEntitiesAsList()));
-    exceptions.add(
-        Try.ofVoid(
-            exceptionString.isPresent(),
-            () ->
-                new InvalidGridException(
-                    duplicateUuidsString(
-                        rawGridElements.getClass().getSimpleName(), exceptionString))));
+    List<Try<Void, ? extends ValidationException>> exceptions =
+        new ArrayList<>(
+            checkForDuplicates(rawGridElements.allEntitiesAsList(), UniqueEntity::getUuid));
 
     /* Checking nodes */
     Set<NodeInput> nodes = rawGridElements.getNodes();
@@ -183,18 +157,18 @@ private GridContainerValidationUtils() {
    * Checks the validity of type ids of every entity.
    *
    * @param rawGridElements the raw grid elements
-   * @return a list of try objects either containing an {@link UnsafeEntityException} or an empty
-   *     Success
+   * @return a list of try objects either containing an {@link DuplicateEntitiesException} or an
+   *     empty Success
    */
-  protected static List<Try<Void, UnsafeEntityException>> checkRawGridTypeIds(
+  protected static List<Try<Void, DuplicateEntitiesException>> checkRawGridTypeIds(
       RawGridElements rawGridElements) {
-    List<Try<Void, UnsafeEntityException>> exceptions = new ArrayList<>();
-    exceptions.addAll(ValidationUtils.checkIds(rawGridElements.getNodes()));
-    exceptions.addAll(ValidationUtils.checkIds(rawGridElements.getLines()));
-    exceptions.addAll(ValidationUtils.checkIds(rawGridElements.getTransformer2Ws()));
-    exceptions.addAll(ValidationUtils.checkIds(rawGridElements.getTransformer3Ws()));
-    exceptions.addAll(ValidationUtils.checkIds(rawGridElements.getSwitches()));
-    exceptions.addAll(ValidationUtils.checkIds(rawGridElements.getMeasurementUnits()));
+    List<Try<Void, DuplicateEntitiesException>> exceptions = new ArrayList<>();
+    exceptions.addAll(checkForDuplicates(rawGridElements.getNodes(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(rawGridElements.getLines(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(rawGridElements.getTransformer2Ws(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(rawGridElements.getTransformer3Ws(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(rawGridElements.getSwitches(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(rawGridElements.getMeasurementUnits(), AssetInput::getId));
 
     return exceptions;
   }
@@ -217,19 +191,10 @@ protected static List<Try<Void, UnsafeEntityException>> checkRawGridTypeIds(
       return List.of(isNull);
     }
 
-    List<Try<Void, ? extends ValidationException>> exceptions = new ArrayList<>();
-
     // sanity check for distinct uuids
-    Optional<String> exceptionString =
-        ValidationUtils.checkForDuplicateUuids(
-            new HashSet<>(systemParticipants.allEntitiesAsList()));
-    exceptions.add(
-        Try.ofVoid(
-            exceptionString.isPresent(),
-            () ->
-                new InvalidGridException(
-                    duplicateUuidsString(
-                        systemParticipants.getClass().getSimpleName(), exceptionString))));
+    List<Try<Void, ? extends ValidationException>> exceptions =
+        new ArrayList<>(
+            checkForDuplicates(systemParticipants.allEntitiesAsList(), UniqueEntity::getUuid));
 
     exceptions.addAll(checkSystemParticipants(systemParticipants.getBmPlants(), nodes));
     exceptions.addAll(checkSystemParticipants(systemParticipants.getChpPlants(), nodes));
@@ -274,23 +239,23 @@ protected static List<Try<Void, UnsafeEntityException>> checkRawGridTypeIds(
    * Checks the validity of type ids of every entity.
    *
    * @param systemParticipants the system participants
-   * @return a list of try objects either containing an {@link UnsafeEntityException} or an empty
-   *     Success
+   * @return a list of try objects either containing an {@link DuplicateEntitiesException} or an
+   *     empty Success
    */
-  protected static List<Try<Void, UnsafeEntityException>> checkSystemParticipantsTypeIds(
+  protected static List<Try<Void, DuplicateEntitiesException>> checkSystemParticipantsTypeIds(
       SystemParticipants systemParticipants) {
-    List<Try<Void, UnsafeEntityException>> exceptions = new ArrayList<>();
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getBmPlants()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getChpPlants()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getEvCS()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getEvs()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getFixedFeedIns()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getHeatPumps()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getLoads()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getPvPlants()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getStorages()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getWecPlants()));
-    exceptions.addAll(ValidationUtils.checkIds(systemParticipants.getEmSystems()));
+    List<Try<Void, DuplicateEntitiesException>> exceptions = new ArrayList<>();
+    exceptions.addAll(checkForDuplicates(systemParticipants.getBmPlants(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getChpPlants(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getEvCS(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getEvs(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getFixedFeedIns(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getHeatPumps(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getLoads(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getPvPlants(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getStorages(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getWecPlants(), AssetInput::getId));
+    exceptions.addAll(checkForDuplicates(systemParticipants.getEmSystems(), AssetInput::getId));
 
     return exceptions;
   }
@@ -312,18 +277,10 @@ protected static List<Try<Void, UnsafeEntityException>> checkSystemParticipantsT
       return List.of(isNull);
     }
 
-    List<Try<Void, ? extends ValidationException>> exceptions = new ArrayList<>();
-
     // sanity check for distinct uuids
-    Optional<String> exceptionString =
-        checkForDuplicateUuids(new HashSet<>(graphicElements.allEntitiesAsList()));
-    exceptions.add(
-        Try.ofVoid(
-            exceptionString.isPresent(),
-            () ->
-                new InvalidGridException(
-                    duplicateUuidsString(
-                        graphicElements.getClass().getSimpleName(), exceptionString))));
+    List<Try<Void, ? extends ValidationException>> exceptions =
+        new ArrayList<>(
+            checkForDuplicates(graphicElements.allEntitiesAsList(), UniqueEntity::getUuid));
 
     graphicElements
         .getNodeGraphics()