Introducing SqlIndividualTimeSeriesMetaInformation & refactorings 2.0 (#524)

* proper refactoring for #513 w/o breaking external interfaces (no tests yet!)

* More deprecations, adapting tests, adding to changelog

* Fixing test

* Specified arguments of deprecation tags

* Small improvement

* SqlIndividualTimeSeriesMetaInformation

* Addressing reviewers comments, providing richer deprecation messages

Co-authored-by: Johannes Hiry <johannes.hiry@tu-dortmund.de>
Co-authored-by: t-ober <63147366+t-ober@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - SQL time series sources (`SqlTimeSeriesSource` and `SqlTimeSeriesMappingSource`) [#467](https://github.com/ie3-institute/PowerSystemDataModel/issues/467)
 - Graph with impedance weighted edges including facilities to create it [#440](https://github.com/ie3-institute/PowerSystemDataModel/issues/440)
+- Introducing `SqlIndividualTimeSeriesMetaInformation` which provides sql table names [#513](https://github.com/ie3-institute/PowerSystemDataModel/issues/513)
 
 ### Fixed
 - Reduced code smells [#492](https://github.com/ie3-institute/PowerSystemDataModel/issues/492)
@@ -26,6 +27,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - BREAKING: Transformer's no load susceptance needs to be zero or negative to pass model validation [#378](https://github.com/ie3-institute/PowerSystemDataModel/issues/378)
   - All input data sets for version < 3.0.0 need to be altered!
+- Deprecating (as part of [#513](https://github.com/ie3-institute/PowerSystemDataModel/issues/513)): 
+  - `edu.ie3.datamodel.io.csv.timeseries.ColumnScheme`
+  - `edu.ie3.datamodel.io.csv.FileNameMetaInformation`
+  - `edu.ie3.datamodel.io.csv.timeseries.IndividualTimeSeriesMetaInformation`
+  - `edu.ie3.datamodel.io.csv.timeseries.LoadProfileTimeSeriesMetaInformation`
+  - `edu.ie3.datamodel.io.connectors.CsvFileConnector.CsvIndividualTimeSeriesMetaInformation`
+  - and related methods
 
 ## [2.1.0] - 2022-01-05
 

src/main/java/edu/ie3/datamodel/io/connectors/CsvFileConnector.java

@@ -8,9 +8,10 @@
 import edu.ie3.datamodel.exceptions.ConnectorException;
 import edu.ie3.datamodel.io.IoUtil;
 import edu.ie3.datamodel.io.csv.*;
-import edu.ie3.datamodel.io.csv.timeseries.ColumnScheme;
-import edu.ie3.datamodel.io.csv.timeseries.IndividualTimeSeriesMetaInformation;
 import edu.ie3.datamodel.io.naming.FileNamingStrategy;
+import edu.ie3.datamodel.io.naming.TimeSeriesMetaInformation;
+import edu.ie3.datamodel.io.naming.timeseries.ColumnScheme;
+import edu.ie3.datamodel.io.naming.timeseries.IndividualTimeSeriesMetaInformation;
 import edu.ie3.datamodel.models.UniqueEntity;
 import edu.ie3.datamodel.models.timeseries.TimeSeries;
 import edu.ie3.datamodel.models.timeseries.TimeSeriesEntry;
@@ -41,7 +42,8 @@ public class CsvFileConnector implements DataConnector {
       new HashMap<>();
   private final Map<UUID, BufferedCsvWriter> timeSeriesWriters = new HashMap<>();
   // ATTENTION: Do not finalize. It's meant for lazy evaluation.
-  private Map<UUID, CsvIndividualTimeSeriesMetaInformation> individualTimeSeriesMetaInformation;
+  private Map<UUID, edu.ie3.datamodel.io.csv.CsvIndividualTimeSeriesMetaInformation>
+      individualTimeSeriesMetaInformation;
   private final FileNamingStrategy fileNamingStrategy;
   private final String baseDirectoryName;
 
@@ -219,8 +221,25 @@ public BufferedReader initReader(String filePath) throws FileNotFoundException {
    *
    * @param timeSeriesUuid The time series in question
    * @return An option on the queried information
+   * @deprecated since 3.0. Use {@link #individualTimeSeriesMetaInformation(UUID)} instead
    */
-  public Optional<IndividualTimeSeriesMetaInformation> getIndividualTimeSeriesMetaInformation(
+  @Deprecated(since = "3.0", forRemoval = true)
+  public Optional<edu.ie3.datamodel.io.csv.timeseries.IndividualTimeSeriesMetaInformation>
+      getIndividualTimeSeriesMetaInformation(UUID timeSeriesUuid) {
+    return individualTimeSeriesMetaInformation(timeSeriesUuid)
+        .map(edu.ie3.datamodel.io.csv.timeseries.IndividualTimeSeriesMetaInformation::new);
+  }
+
+  /**
+   * Get time series meta information for a given uuid.
+   *
+   * <p>This method lazily evaluates the mapping from <i>all</i> time series files to their meta
+   * information.
+   *
+   * @param timeSeriesUuid The time series in question
+   * @return An option on the queried information
+   */
+  public Optional<IndividualTimeSeriesMetaInformation> individualTimeSeriesMetaInformation(
       UUID timeSeriesUuid) {
     if (Objects.isNull(individualTimeSeriesMetaInformation))
       individualTimeSeriesMetaInformation = buildIndividualTimeSeriesMetaInformation();
@@ -233,7 +252,7 @@ public Optional<IndividualTimeSeriesMetaInformation> getIndividualTimeSeriesMeta
    *
    * @return Mapping from time series uuid to it's meta information.
    */
-  private Map<UUID, CsvIndividualTimeSeriesMetaInformation>
+  private Map<UUID, edu.ie3.datamodel.io.csv.CsvIndividualTimeSeriesMetaInformation>
       buildIndividualTimeSeriesMetaInformation() {
     return getIndividualTimeSeriesFilePaths().parallelStream()
         .map(
@@ -242,11 +261,11 @@ public Optional<IndividualTimeSeriesMetaInformation> getIndividualTimeSeriesMeta
               String filePathWithoutEnding = removeFileEnding(filePath);
               IndividualTimeSeriesMetaInformation metaInformation =
                   (IndividualTimeSeriesMetaInformation)
-                      fileNamingStrategy.extractTimeSeriesMetaInformation(filePathWithoutEnding);
-              return new CsvIndividualTimeSeriesMetaInformation(
+                      fileNamingStrategy.timeSeriesMetaInformation(filePathWithoutEnding);
+              return new edu.ie3.datamodel.io.csv.CsvIndividualTimeSeriesMetaInformation(
                   metaInformation, filePathWithoutEnding);
             })
-        .collect(Collectors.toMap(FileNameMetaInformation::getUuid, v -> v));
+        .collect(Collectors.toMap(TimeSeriesMetaInformation::getUuid, v -> v));
   }
 
   /**
@@ -257,7 +276,7 @@ public Optional<IndividualTimeSeriesMetaInformation> getIndividualTimeSeriesMeta
    *     possible readers will be initialized.
    * @return A mapping from column scheme to the individual time series meta information
    */
-  public Map<ColumnScheme, Set<CsvIndividualTimeSeriesMetaInformation>>
+  public Map<ColumnScheme, Set<edu.ie3.datamodel.io.csv.CsvIndividualTimeSeriesMetaInformation>>
       getCsvIndividualTimeSeriesMetaInformation(ColumnScheme... columnSchemes) {
     return getIndividualTimeSeriesFilePaths().parallelStream()
         .map(
@@ -269,7 +288,8 @@ public Optional<IndividualTimeSeriesMetaInformation> getIndividualTimeSeriesMeta
         .map(Optional::get)
         .collect(
             Collectors.groupingBy(
-                CsvIndividualTimeSeriesMetaInformation::getColumnScheme, Collectors.toSet()));
+                edu.ie3.datamodel.io.csv.CsvIndividualTimeSeriesMetaInformation::getColumnScheme,
+                Collectors.toSet()));
   }
 
   /**
@@ -322,11 +342,11 @@ private Set<String> getIndividualTimeSeriesFilePaths() {
    *     allowed.
    * @return An {@link Optional} to {@link IndividualTimeSeriesMetaInformation}
    */
-  private Optional<CsvIndividualTimeSeriesMetaInformation> buildCsvTimeSeriesMetaInformation(
-      String filePathString, ColumnScheme... columnSchemes) {
+  private Optional<edu.ie3.datamodel.io.csv.CsvIndividualTimeSeriesMetaInformation>
+      buildCsvTimeSeriesMetaInformation(String filePathString, ColumnScheme... columnSchemes) {
     try {
-      FileNameMetaInformation metaInformation =
-          fileNamingStrategy.extractTimeSeriesMetaInformation(filePathString);
+      TimeSeriesMetaInformation metaInformation =
+          fileNamingStrategy.timeSeriesMetaInformation(filePathString);
       if (!IndividualTimeSeriesMetaInformation.class.isAssignableFrom(metaInformation.getClass())) {
         log.error(
             "The time series file '{}' does not represent an individual time series.",
@@ -350,7 +370,7 @@ private Optional<CsvIndividualTimeSeriesMetaInformation> buildCsvTimeSeriesMetaI
         return Optional.empty();
       }
       return Optional.of(
-          new CsvIndividualTimeSeriesMetaInformation(
+          new edu.ie3.datamodel.io.csv.CsvIndividualTimeSeriesMetaInformation(
               individualMetaInformation.getUuid(),
               individualMetaInformation.getColumnScheme(),
               filePathString));
@@ -433,19 +453,28 @@ public void shutdown() {
             });
   }
 
-  /** Enhancing the {@link IndividualTimeSeriesMetaInformation} with the full path to csv file */
+  /**
+   * Enhancing the {@link IndividualTimeSeriesMetaInformation} with the full path to csv file
+   *
+   * @deprecated since 3.0. Use {@link
+   *     edu.ie3.datamodel.io.csv.CsvIndividualTimeSeriesMetaInformation} instead
+   */
+  @Deprecated(since = "3.0", forRemoval = true)
   public static class CsvIndividualTimeSeriesMetaInformation
-      extends IndividualTimeSeriesMetaInformation {
+      extends edu.ie3.datamodel.io.csv.timeseries.IndividualTimeSeriesMetaInformation {
     private final String fullFilePath;
 
     public CsvIndividualTimeSeriesMetaInformation(
-        UUID uuid, ColumnScheme columnScheme, String fullFilePath) {
+        UUID uuid,
+        edu.ie3.datamodel.io.csv.timeseries.ColumnScheme columnScheme,
+        String fullFilePath) {
       super(uuid, columnScheme);
       this.fullFilePath = fullFilePath;
     }
 
     public CsvIndividualTimeSeriesMetaInformation(
-        IndividualTimeSeriesMetaInformation metaInformation, String fullFilePath) {
+        edu.ie3.datamodel.io.csv.timeseries.IndividualTimeSeriesMetaInformation metaInformation,
+        String fullFilePath) {
       this(metaInformation.getUuid(), metaInformation.getColumnScheme(), fullFilePath);
     }
 

src/main/java/edu/ie3/datamodel/io/csv/CsvIndividualTimeSeriesMetaInformation.java

@@ -0,0 +1,57 @@
+/*
+ * © 2022. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.io.csv;
+
+import edu.ie3.datamodel.io.naming.timeseries.ColumnScheme;
+import edu.ie3.datamodel.io.naming.timeseries.IndividualTimeSeriesMetaInformation;
+import java.util.Objects;
+import java.util.UUID;
+
+/** Enhancing the {@link IndividualTimeSeriesMetaInformation} with the full path to csv file */
+public class CsvIndividualTimeSeriesMetaInformation extends IndividualTimeSeriesMetaInformation {
+  private final String fullFilePath;
+
+  public CsvIndividualTimeSeriesMetaInformation(
+      UUID uuid, ColumnScheme columnScheme, String fullFilePath) {
+    super(uuid, columnScheme);
+    this.fullFilePath = fullFilePath;
+  }
+
+  public CsvIndividualTimeSeriesMetaInformation(
+      IndividualTimeSeriesMetaInformation metaInformation, String fullFilePath) {
+    this(metaInformation.getUuid(), metaInformation.getColumnScheme(), fullFilePath);
+  }
+
+  public String getFullFilePath() {
+    return fullFilePath;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (!(o instanceof CsvIndividualTimeSeriesMetaInformation that)) return false;
+    if (!super.equals(o)) return false;
+    return fullFilePath.equals(that.fullFilePath);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(super.hashCode(), fullFilePath);
+  }
+
+  @Override
+  public String toString() {
+    return "CsvIndividualTimeSeriesMetaInformation{"
+        + "uuid="
+        + getUuid()
+        + ", columnScheme="
+        + getColumnScheme()
+        + ", fullFilePath='"
+        + fullFilePath
+        + '\''
+        + '}';
+  }
+}

src/main/java/edu/ie3/datamodel/io/csv/FileNameMetaInformation.java

@@ -8,7 +8,12 @@
 import java.util.Objects;
 import java.util.UUID;
 
-/** Meta information, that can be derived from a certain file name */
+/**
+ * Meta information, that can be derived from a certain file name
+ *
+ * @deprecated since 3.0. Use {@link edu.ie3.datamodel.io.naming.TimeSeriesMetaInformation} instead
+ */
+@Deprecated(since = "3.0", forRemoval = true)
 public abstract class FileNameMetaInformation {
   private final UUID uuid;
 

src/main/java/edu/ie3/datamodel/io/csv/timeseries/ColumnScheme.java

@@ -11,7 +11,12 @@
 import java.util.Objects;
 import java.util.Optional;
 
-/** Yet supported column schemes in individual time series */
+/**
+ * Yet supported column schemes in individual time series
+ *
+ * @deprecated since 3.0. Use {@link edu.ie3.datamodel.io.naming.timeseries.ColumnScheme} instead
+ */
+@Deprecated(since = "3.0", forRemoval = true)
 public enum ColumnScheme {
   ENERGY_PRICE("c", EnergyPriceValue.class),
   ACTIVE_POWER("p", PValue.class),
@@ -24,6 +29,7 @@ public enum ColumnScheme {
   private final String scheme;
   private final Class<? extends Value> valueClass;
 
+  @Deprecated
   ColumnScheme(String scheme, Class<? extends Value> valueClass) {
     this.scheme = scheme;
     this.valueClass = valueClass;

src/main/java/edu/ie3/datamodel/io/csv/timeseries/IndividualTimeSeriesMetaInformation.java

@@ -9,7 +9,13 @@
 import java.util.Objects;
 import java.util.UUID;
 
-/** Specific meta information, that can be derived from a individual time series file */
+/**
+ * Specific meta information, that can be derived from a individual time series file
+ *
+ * @deprecated since 3.0. Use {@link
+ *     edu.ie3.datamodel.io.naming.timeseries.IndividualTimeSeriesMetaInformation} instead
+ */
+@Deprecated(since = "3.0", forRemoval = true)
 public class IndividualTimeSeriesMetaInformation extends FileNameMetaInformation {
   private final ColumnScheme columnScheme;
 
@@ -18,6 +24,20 @@ public IndividualTimeSeriesMetaInformation(UUID uuid, ColumnScheme columnScheme)
     this.columnScheme = columnScheme;
   }
 
+  public IndividualTimeSeriesMetaInformation(
+      edu.ie3.datamodel.io.naming.timeseries.IndividualTimeSeriesMetaInformation
+          newMetaInformation) {
+    super(newMetaInformation.getUuid());
+    this.columnScheme =
+        ColumnScheme.parse(newMetaInformation.getColumnScheme().toString())
+            .orElseThrow(
+                () ->
+                    new RuntimeException(
+                        "Cannot convert new column scheme "
+                            + newMetaInformation.getColumnScheme().getScheme()
+                            + " to deprecated column scheme!"));
+  }
+
   public ColumnScheme getColumnScheme() {
     return columnScheme;
   }

src/main/java/edu/ie3/datamodel/io/csv/timeseries/LoadProfileTimeSeriesMetaInformation.java

@@ -9,7 +9,13 @@
 import java.util.Objects;
 import java.util.UUID;
 
-/** Specific meta information, that can be derived from a load profile time series file */
+/**
+ * Specific meta information, that can be derived from a load profile time series file
+ *
+ * @deprecated since 3.0. Use {@link
+ *     edu.ie3.datamodel.io.naming.timeseries.LoadProfileTimeSeriesMetaInformation} instead
+ */
+@Deprecated(since = "3.0", forRemoval = true)
 public class LoadProfileTimeSeriesMetaInformation extends FileNameMetaInformation {
   private final String profile;
 
@@ -18,6 +24,12 @@ public LoadProfileTimeSeriesMetaInformation(UUID uuid, String profile) {
     this.profile = profile;
   }
 
+  public LoadProfileTimeSeriesMetaInformation(
+      edu.ie3.datamodel.io.naming.timeseries.LoadProfileTimeSeriesMetaInformation metaInformation) {
+    super(metaInformation.getUuid());
+    this.profile = metaInformation.getProfile();
+  }
+
   public String getProfile() {
     return profile;
   }