Refactoring data connections and container.

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Removed Jenkinsfile [#290](https://github.com/ie3-institute/simonaAPI/issues/290)
 - Adapted dependabot workflow and added CODEOWNERS [#294](https://github.com/ie3-institute/simonaAPI/issues/294)
+- Refactoring external data connection [#267](https://github.com/ie3-institute/simonaAPI/issues/267)
+- Refactoring data containers [#268](https://github.com/ie3-institute/simonaAPI/issues/268)
 
 ## [0.9.0] - 2025-05-09
 

docs/readthedocs/connections/connections.md

@@ -1 +1,41 @@
 # Data connections
+
+In order to exchange data between SIMONA and an external simulation, this API defines some data connections.
+
+The data connections provided by the API can be divided into three kinds of data connections:
+1. Input data connections
+2. Output data connections
+3. Bidirectional data connections
+
+## Input data connections
+
+These data connections are used to provide SIMONA with external data. Each input data connection contains two references
+for SIMONA actors. The first reference is for the actual service within SIMONA that will receive the external data. The second
+reference is for the external simulation adapter. The adapter will receive a message to schedule the data service in SIMONA.
+
+The process of sending data to the service and asking for scheduling of the service is taken care of by the method `sendExtMsg`.
+In order to send a message, simply call the method with the message as input.
+
+Currently, the following input data connections are provided:
+- ExtPrimaryDataConnection
+
+
+## Output data connections
+
+These data connections are used to provide SIMONA response messages to the external simulation. Each output data connection
+has a queue for messages send by SIMONA. The result data connection itself cannot send messages to SIMONA.
+
+Currently, the following input data connections are provided:
+- ExtResultListener
+
+
+## Bidirectional data connections
+
+The bidirectional data connection combines the functionality of both input and output data connections. These data connections
+can be used to send data to SIMONA and receive responses. Also, one additional feature is, that a bidirectional data connections
+can request responses, e.g. SIMONA results.
+
+Currently, the following input data connections are provided:
+- ExtEmDataConnection
+- ExtEvDataConnection
+- ExtResultDataConnection

src/main/java/edu/ie3/simona/api/data/ExtDataContainerQueue.java

@@ -0,0 +1,63 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.simona.api.data;
+
+import edu.ie3.simona.api.data.container.ExtDataContainer;
+import java.util.concurrent.LinkedBlockingDeque;
+import java.util.function.Function;
+
+/** Data queue to allow data flow between SimonaAPI and an external simulation */
+public final class ExtDataContainerQueue<V extends ExtDataContainer> {
+  private final LinkedBlockingDeque<V> receiverTriggerDeque = new LinkedBlockingDeque<>();
+
+  /**
+   * Method for adding an {@link ExtDataContainer} to the queue.
+   *
+   * @param data to be added
+   * @throws InterruptedException if the thread running this has been interrupted during the
+   *     blocking operation
+   */
+  public void queueData(V data) throws InterruptedException {
+    receiverTriggerDeque.putLast(data);
+  }
+
+  /**
+   * Method to take an {@link ExtDataContainer} from the queue. This method waits (blocks) until
+   * data is added to the queue.
+   *
+   * @return a data container
+   * @throws InterruptedException if the thread running this has been interrupted during the
+   *     blocking operation
+   */
+  public V takeContainer() throws InterruptedException {
+    return receiverTriggerDeque.takeFirst();
+  }
+
+  /**
+   * Method to take only a part of a container from the queue. This method waits (blocks) until data
+   * is added to the queue.
+   *
+   * @param extractor function to extract a part of the container
+   * @return the extracted part
+   * @param <R> type of returned value
+   * @throws InterruptedException if the thread running this has been interrupted during the
+   *     blocking operation
+   */
+  public <R> R takeData(Function<V, R> extractor) throws InterruptedException {
+    // removes the first container from the queue
+    V data = receiverTriggerDeque.takeFirst();
+    R result = extractor.apply(data);
+
+    // if the container is not empty, it should remain in the queue.
+    // else the container needs to be removed
+    if (!data.isEmpty()) {
+      receiverTriggerDeque.putFirst(data);
+    }
+
+    return result;
+  }
+}

src/main/java/edu/ie3/simona/api/data/connection/BiDirectional.java

@@ -0,0 +1,58 @@
+/*
+ * © 2025. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+
+package edu.ie3.simona.api.data.connection;
+
+import edu.ie3.simona.api.data.ontology.DataMessageFromExt;
+import edu.ie3.simona.api.data.ontology.DataResponseMessageToExt;
+import edu.ie3.simona.api.exceptions.WrongResponseTypeException;
+import java.util.concurrent.LinkedBlockingQueue;
+
+/**
+ * Enables bidirectional communication when extended by an external data connection.
+ *
+ * @param <M> type of message to SIMONA
+ * @param <R> type of response messages to ext
+ */
+public abstract non-sealed class BiDirectional<
+        M extends DataMessageFromExt, R extends DataResponseMessageToExt>
+    extends ExtInputDataConnection<M> implements ExtOutputDataConnection<R> {
+
+  /** Data message queue containing messages from SIMONA */
+  public final LinkedBlockingQueue<R> receiveTriggerQueue = new LinkedBlockingQueue<>();
+
+  protected BiDirectional() {
+    super();
+  }
+
+  @Override
+  public final void queueExtResponseMsg(R msg) throws InterruptedException {
+    receiveTriggerQueue.put(msg);
+  }
+
+  @Override
+  public final R receiveAny() throws InterruptedException {
+    return receiveTriggerQueue.take();
+  }
+
+  @Override
+  @SuppressWarnings("unchecked")
+  public final <T extends R> T receiveWithType(Class<T> expectedMessageClass)
+      throws InterruptedException {
+    // blocks until actor puts something here
+    R msg = receiveTriggerQueue.take();
+
+    if (msg.getClass().equals(expectedMessageClass)) {
+      return (T) msg;
+    } else
+      throw new WrongResponseTypeException(
+          "Received unexpected message '"
+              + msg
+              + "', expected type '"
+              + expectedMessageClass
+              + "'");
+  }
+}

src/main/java/edu/ie3/simona/api/data/ExtDataConnection.java → src/main/java/edu/ie3/simona/api/data/connection/ExtDataConnection.java

@@ -4,7 +4,7 @@
  * Research group Distribution grid planning and operation
  */
 
-package edu.ie3.simona.api.data;
+package edu.ie3.simona.api.data.connection;
 
 /** Interface that defines a data connection between SIMONA and an external simulation. */
 public interface ExtDataConnection {}