Merge pull request #360 from ie3-institute/ms/#355-enhance-ExtEntityMapping

Enhance external entity mapping.

Author: sebastian-peter

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Updated the maven central publishing scripts [#339](https://github.com/ie3-institute/simonaAPI/issues/339)
 - Refactoring `ExtSimAdapterData` [#347](https://github.com/ie3-institute/simonaAPI/issues/347)
+- Enhanced `ExtEntityMapping` [#355](https://github.com/ie3-institute/simonaAPI/issues/355)
 
 ## [0.10.0] - 2025-09-10
 

src/main/java/edu/ie3/simona/api/mapping/ExtEntityMapping.java

@@ -6,98 +6,324 @@
 
 package edu.ie3.simona.api.mapping;
 
+import edu.ie3.datamodel.io.naming.timeseries.ColumnScheme;
+import edu.ie3.datamodel.models.input.container.GridContainer;
+import edu.ie3.datamodel.models.value.Value;
 import java.util.*;
-import java.util.stream.Collectors;
-import java.util.stream.Stream;
 
 /** Contains the mapping between SIMONA uuid, the external id and the data type the assets hold */
 public class ExtEntityMapping {
 
-  private final Map<DataType, List<ExtEntityEntry>> extEntities;
+  private final EnumMap<DataType, List<UUID>> extAssets = new EnumMap<>(DataType.class);
+  private final Map<UUID, Class<? extends Value>> primaryMapping = new HashMap<>();
 
-  public ExtEntityMapping(List<ExtEntityEntry> extEntityEntryList) {
-    this.extEntities =
-        extEntityEntryList.stream().collect(Collectors.groupingBy(ExtEntityEntry::dataType));
+  // asset lists
+  private final Set<UUID> gridAssets = new HashSet<>();
+  private final Set<UUID> participants = new HashSet<>();
+  private final Set<UUID> ems = new HashSet<>();
+
+  private final Map<UUID, String> uuidToId = new HashMap<>();
+  private final Map<String, UUID> idToUuid = new HashMap<>();
+
+  public ExtEntityMapping(List<ExtEntityEntry> entries) {
+    entries.forEach(
+        entry -> {
+          DataType dataType = entry.dataType();
+          UUID uuid = entry.uuid();
+          String id = entry.id();
+
+          entry
+              .columnScheme()
+              .ifPresent(scheme -> primaryMapping.put(uuid, scheme.getValueClass()));
+
+          // override mappings
+          uuidToId.put(uuid, id);
+          idToUuid.put(id, uuid);
+
+          extAssets.computeIfAbsent(dataType, k -> new ArrayList<>()).add(uuid);
+        });
+  }
+
+  /**
+   * Creates a mapping based on the uuids and ids found in the provided grid.
+   *
+   * @param grid that contains some mapping information
+   */
+  public ExtEntityMapping(GridContainer grid) {
+    // handling of grid assets
+    grid.getRawGrid()
+        .allEntitiesAsList()
+        .forEach(
+            asset -> {
+              UUID uuid = asset.getUuid();
+              String id = asset.getId();
+
+              // add to mappings
+              uuidToId.put(uuid, id);
+              idToUuid.put(id, uuid);
+
+              // add to asset list
+              gridAssets.add(asset.getUuid());
+            });
+
+    // handling of participants and ems
+    grid.getSystemParticipants()
+        .allEntitiesAsList()
+        .forEach(
+            participant -> {
+              UUID uuid = participant.getUuid();
+              String id = participant.getId();
+
+              // add to mappings
+              uuidToId.put(uuid, id);
+              idToUuid.put(id, uuid);
+
+              // add to asset list
+              participants.add(participant.getUuid());
+
+              // add ems
+              participant
+                  .getControllingEm()
+                  .ifPresent(
+                      em -> {
+                        UUID emUuid = em.getUuid();
+                        String emId = em.getId();
+
+                        // add to mappings
+                        uuidToId.put(emUuid, emId);
+                        idToUuid.put(emId, emUuid);
+
+                        // add to asset list
+                        ems.add(emUuid);
+                      });
+            });
+  }
+
+  /**
+   * Used to copy another mapping.
+   *
+   * @param mapping that should be copied
+   */
+  private ExtEntityMapping(ExtEntityMapping mapping) {
+    this.extAssets.putAll(mapping.extAssets);
+    this.primaryMapping.putAll(mapping.primaryMapping);
+    this.gridAssets.addAll(mapping.gridAssets);
+    this.participants.addAll(mapping.participants);
+    this.ems.addAll(mapping.ems);
+    this.uuidToId.putAll(mapping.uuidToId);
+    this.idToUuid.putAll(mapping.idToUuid);
+  }
+
+  /**
+   * Method to add entities that should be used for the data connection.
+   *
+   * <p>Note: This method can override the existing uuid-id mapping!
+   *
+   * @param included a list of entries
+   * @return an updated mapping
+   */
+  public ExtEntityMapping include(List<ExtEntityEntry> included) {
+    ExtEntityMapping copy = new ExtEntityMapping(this);
+    copy.includeEntries(included);
+    return copy;
+  }
+
+  /**
+   * Method to specify entities that should be used for the data connection. The ids are matched
+   * against the uuid-id mapping that is already know.
+   *
+   * @param included a list of ids
+   * @return an updated mapping
+   */
+  public ExtEntityMapping include(
+      DataType dataType, List<String> included, Optional<ColumnScheme> schemeOption) {
+    ExtEntityMapping copy = new ExtEntityMapping(this);
+    List<UUID> includedUuids =
+        included.stream().map(this::get).filter(Optional::isPresent).map(Optional::get).toList();
+
+    schemeOption.ifPresent(
+        scheme -> includedUuids.forEach(uuid -> primaryMapping.put(uuid, scheme.getValueClass())));
+    addExtEntities(dataType, includedUuids);
+
+    return copy;
+  }
+
+  protected void includeIds(
+      DataType dataType, List<UUID> included, Optional<ColumnScheme> schemeOption) {
+    schemeOption.ifPresent(
+        scheme -> included.forEach(uuid -> primaryMapping.put(uuid, scheme.getValueClass())));
+    addExtEntities(dataType, included);
+  }
+
+  /**
+   * Method to add entities that should be used for the data connection.
+   *
+   * <p>Note: This method can override the existing uuid-id mapping!
+   *
+   * @param included a list of entries
+   */
+  private void includeEntries(List<ExtEntityEntry> included) {
+    included.forEach(
+        entry -> {
+          DataType dataType = entry.dataType();
+          UUID uuid = entry.uuid();
+          String id = entry.id();
+
+          entry
+              .columnScheme()
+              .ifPresent(scheme -> primaryMapping.put(uuid, scheme.getValueClass()));
+
+          // override mappings
+          uuidToId.put(uuid, id);
+          idToUuid.put(id, uuid);
+
+          addExtEntities(dataType, included.stream().map(ExtEntityEntry::uuid).toList());
+        });
+  }
+
+  /**
+   * Method to handle adding the entities to the {@link #extAssets} map.
+   *
+   * @param dataType for which assets are added
+   * @param included a list of included uuids
+   */
+  private void addExtEntities(DataType dataType, List<UUID> included) {
+    if (dataType == DataType.PRIMARY_RESULT) {
+      extAssets.computeIfAbsent(DataType.PRIMARY, d -> new ArrayList<>()).addAll(included);
+      extAssets.computeIfAbsent(DataType.RESULT, d -> new ArrayList<>()).addAll(included);
+    } else {
+      extAssets.computeIfAbsent(dataType, k -> new ArrayList<>()).addAll(included);
+    }
   }
 
   /** Returns the data types of this mapping. */
   public Set<DataType> getDataTypes() {
-    return extEntities.keySet();
+    return extAssets.keySet();
+  }
+
+  /** Returns a map: uuid to primary data class. */
+  public Map<UUID, Class<? extends Value>> getPrimaryMapping() {
+    return Collections.unmodifiableMap(primaryMapping);
+  }
+
+  /** Returns a list of all external assets. */
+  public List<UUID> getAllAssets() {
+    return extAssets.values().stream().flatMap(Collection::stream).toList();
   }
 
   /**
-   * Method for getting the external entity entries for a specific data type.
+   * Method to return all assets of a specific data type. If no external assets are set, all assets
+   * that are provided by a grid are used. In case external entities are present, they will be used
+   * to filter the grid assets. If no grid assets are present, only the external assets will be
+   * returned.
    *
-   * @param dataType for which entries should be returned
-   * @return a list containing all entries or an empty list
+   * @param dataType for which assets should be returned
+   * @return a list of uuids
    */
-  public List<ExtEntityEntry> getEntries(DataType dataType) {
-    return extEntities.getOrDefault(dataType, Collections.emptyList());
+  public List<UUID> getAssets(DataType dataType) {
+    List<UUID> uuids =
+        switch (dataType) {
+          case PRIMARY, PRIMARY_RESULT -> new ArrayList<>(participants);
+          case RESULT -> {
+            List<UUID> res = new ArrayList<>();
+            res.addAll(gridAssets);
+            res.addAll(participants);
+            res.addAll(ems);
+            yield res;
+          }
+          case EM -> new ArrayList<>(ems);
+        };
+
+    if (uuids.isEmpty()) {
+      if (dataType == DataType.PRIMARY_RESULT) {
+        List<UUID> res = new ArrayList<>();
+        res.addAll(extAssets.getOrDefault(DataType.PRIMARY, Collections.emptyList()));
+        res.addAll(extAssets.getOrDefault(DataType.RESULT, Collections.emptyList()));
+
+        return res;
+      } else {
+        return extAssets.getOrDefault(dataType, Collections.emptyList());
+      }
+
+    } else {
+      List<UUID> ext = new ArrayList<>();
+      extAssets.values().forEach(ext::addAll);
+
+      if (extAssets.isEmpty()) {
+        return uuids;
+      } else {
+        return uuids.stream().filter(ext::contains).toList();
+      }
+    }
   }
 
   /**
-   * Returns the full mapping external id to SIMONA uuid. Equals {@code
-   * getExtId2UuidMapping(DataType.values())}.
+   * Checks if the mapping contains the given id.
+   *
+   * @param id to check
+   * @return {@code true}, if a mapping is found.
    */
-  public Map<String, UUID> getExtId2UuidMapping() {
-    return extEntities.values().stream()
-        .flatMap(Collection::stream)
-        .collect(Collectors.toMap(ExtEntityEntry::id, ExtEntityEntry::uuid));
+  public boolean contains(String id) {
+    return idToUuid.containsKey(id);
   }
 
   /**
-   * Returns the full mapping SIMONA uuid to external id. Equals {@code
-   * getExtUuid2IdMapping(DataType.values())}.
+   * Checks if the mapping contains the given uuid.
+   *
+   * @param uuid to check
+   * @return {@code true}, if a mapping is found.
    */
-  public Map<UUID, String> getExtUuid2IdMapping() {
-    return extEntities.values().stream()
-        .flatMap(Collection::stream)
-        .collect(Collectors.toMap(ExtEntityEntry::uuid, ExtEntityEntry::id));
+  public boolean contains(UUID uuid) {
+    return uuidToId.containsKey(uuid);
   }
 
   /**
-   * Mapping external id to SIMONA uuid.
+   * Method to convert a given id into an uuid.
    *
-   * @param dataType data type the external asset expects
-   * @return mapping external id to SIMONA uuid
+   * @param id to convert
+   * @return the uuid or {@code null}, if no mapping exists
    */
-  public Map<String, UUID> getExtId2UuidMapping(DataType dataType) {
-    return extEntities.getOrDefault(dataType, Collections.emptyList()).stream()
-        .collect(Collectors.toMap(ExtEntityEntry::id, ExtEntityEntry::uuid));
+  public UUID from(String id) {
+    return idToUuid.get(id);
   }
 
   /**
-   * Mapping external id to SIMONA uuid.
+   * Method to convert a given uuid into an id.
    *
-   * @param dataTypes the external asset expects
-   * @return mapping external id to SIMONA uuid
+   * @param uuid to convert
+   * @return the uuid or {@code null}, if no mapping exists
    */
-  public Map<String, UUID> getExtId2UuidMapping(DataType... dataTypes) {
-    return Stream.of(dataTypes)
-        .flatMap(type -> extEntities.getOrDefault(type, Collections.emptyList()).stream())
-        .collect(Collectors.toMap(ExtEntityEntry::id, ExtEntityEntry::uuid));
+  public String from(UUID uuid) {
+    return uuidToId.get(uuid);
   }
 
   /**
-   * Mapping SIMONA uuid to external id.
+   * Method that tries to convert the given id into an uuid.
    *
-   * @param dataType data type the external asset expects
-   * @return mapping SIMONA uuid to external id
+   * @param id to convert
+   * @return an option for an uuid or {@link Optional#empty()}, if no mapping exists
    */
-  public Map<UUID, String> getExtUuid2IdMapping(DataType dataType) {
-    return extEntities.getOrDefault(dataType, Collections.emptyList()).stream()
-        .collect(Collectors.toMap(ExtEntityEntry::uuid, ExtEntityEntry::id));
+  public Optional<UUID> get(String id) {
+    return Optional.ofNullable(idToUuid.get(id));
   }
 
   /**
-   * Mapping SIMONA uuid to external id.
+   * Method that tries to convert the given uuid into an id.
    *
-   * @param dataTypes data types the external asset expects
-   * @return mapping SIMONA uuid to external id
+   * @param uuid to convert
+   * @return an option for an id or {@link Optional#empty()}, if no mapping exists
    */
-  public Map<UUID, String> getExtUuid2IdMapping(DataType... dataTypes) {
-    return Stream.of(dataTypes)
-        .flatMap(type -> extEntities.getOrDefault(type, Collections.emptyList()).stream())
-        .collect(Collectors.toMap(ExtEntityEntry::uuid, ExtEntityEntry::id));
+  public Optional<String> get(UUID uuid) {
+    return Optional.ofNullable(uuidToId.get(uuid));
+  }
+
+  /** Returns the full mapping external id to SIMONA uuid. */
+  public Map<String, UUID> getExtId2UuidMapping() {
+    return Collections.unmodifiableMap(idToUuid);
+  }
+
+  /** Returns the full mapping SIMONA uuid to external id. */
+  public Map<UUID, String> getExtUuid2IdMapping() {
+    return Collections.unmodifiableMap(uuidToId);
   }
 }