Draft 1 docu

combined.qmd

@@ -0,0 +1,2 @@
+{{< include paul.qmd >}}
+{{< include luca.qmd >}}

paul.qmd

@@ -0,0 +1,133 @@
+---
+title: "Programmentwurf Advanced SoftwareEngineering"
+subtitle: Für einen [PIC16f84-Simulator](https://git.paulmartin.cloud/paul/PIC-Simu)
+author:
+    - Luca Müller
+    - Paul Martin 
+date: 05/31/2025
+date-format: "DD.MM.YYYY"
+lang: de
+format:
+    pdf:
+        toc: true
+        number-sections: true
+        colorlinks: true
+crossref:
+    custom:
+      - kind: float
+        reference-prefix: UML-Diagramm
+        key: uml
+        latex-env: uml
+        latex-list-of-description: UML-Diagramme
+---
+
+\newcommand*\listofumlsde{\listof{uml}{Verzeichnis der UML-Diagramme}}
+\listofumlsde
+
+{{< pagebreak >}}
+
+# Entwurfsmuster
+Zusätzlich zu den beiden im Folgenden dargestellten Entwursmustern benutzen wir einen [Service Locator](https://en.wikipedia.org/wiki/Service_locator_pattern), der zu den [Architectural Patterns](https://en.wikipedia.org/wiki/Architectural_pattern) zählt. Dieses Pattern nutzt ein `HashMap`, in der verschiedene Komponenten des Programms gespeichert werden, um das Komponenten-Management zu vereinfachen und explizite Abhängigkeiten der Komponenten untereinander zu vermeiden, die das Initialisieren der einzelnen Komponenten erschweren könnten. 
+In unserem Projekt fungiert [`PICComponentLocator`] als dieser Locator. Er besitzt einen `componentCatalogue` als Member, der eine `Map<Class<? extends PICComponentInterface>, PICComponentInterface>` ist. Das bedeutet, dass alle Klassen, die durch den Locator gemanaget werden sollen, das `PICComponentInterface` implementieren müssen. Dieses ist wie folgt [definiert]: 
+```java
+public interface PICComponentInterface {
+    void initialize(PICComponentLocator picComponents);
+}
+```
+Um nicht bei allen Zugriffen die `PICComponentLocator.getComponent()` ausführen zu müssen, wurde zusätzlich die `abstract` Klasse `PICComponent` [eingeführt]. Sie besitzt als Member alle implementierten Komponenten, also sollten neue Komponenten ebenfalls das Interface implementieren und als Member in `PICComponent` angelegt werden. Alle Komponenten können diese Klasse `extend`en und dadurch auch alle weiteren Komponenten als Member haben. Durch die `initialize`-Funktion des `PICComponent` werden durch einen Aufruf der `PICComponentLocator.initAll()` alle Member vom Locator geholt. 
+
+## Marker-Entwurfsmuster
+[Marker-Patterns](https://en.wikipedia.org/wiki/Marker_interface_pattern) werden allgemein genutzt, um Klassen Metadaten zuzuordnen. In unserem Projekt stellen die `FrontendSpecific`-Interfaces Marker dar, die genutzt werden um zu kommunizieren, dass Klassen andere Klassen benötigen, die Frontend-spezifisch sind und somit besonders beachtet werden müssen. So können alle [`Interface`s](LINK ZU ORDNER) definiert werden ohne direkt von fremdem Code abhängig zu sein. Bei möglichen anderen Frontend-Implementierungen müssten entsprechend nur die passenden Klassen die jeweiligen Interfaces implementieren und nichts an den Interfaces ändern.
+Eingeführt wurden die `FrontendSpecific`s in [Commit 06e9348016](https://git.paulmartin.cloud/paul/PIC-Simu/commit/06e934801645e32dea5415ccb4f38368a1667df6) ([hier](https://git.paulmartin.cloud/paul/PIC-Simu/commit/ef3b0fce5f9b6cce06494ff6ce59f5534064e7d2) verfollständigt). Es wurde zunächst ein `FrontendSpecificObject`-Interface angelegt, das alle Frontend-spezifischen Klassen beschreibt, die von Methoden anderer Klassen genutzt werden (sprich, die in den  [`Interface`s](LINK ZU ORDNER) vorkommen). Es ist - entsprechend des Marker-Patterns - komplett leer [definiert](src/main/java/fabrik/simulator/pic16f84/frontendspecifics/FrontendSpecificObject.java):
+```java
+public interface FrontendSpecificObject { 
+}
+```
+Zusätzlich gibt es für spezifische Frontend-Klassen auch `FrontendSpecific`-Interfaces, sodass nach wie vor nur bestimmte Klassen über- bzw. zurückgegeben werden können. Diese spezifischen Interfaces sind ebenfalls leer, nur nutzen sie `extends FrontendSpecificObject` um zu verdeutlichen, dass sie zu den allgemeinen `FrontendSpecificObject`s gehören. Hier beispielsweise [`FrontendSpecificCircle`](src/main/java/fabrik/simulator/pic16f84/frontendspecifics/FrontendSpecificCircle.java):
+```java
+public interface FrontendSpecificCircle extends FrontendSpecificObject {
+}
+```
+Tatsächlich genutzt werden die `FrontendSpecific`-Interfaces von [Circle], [ToggleButtonGroup] und [Vbox]. Sie `extenden` ihr jeweiliges `JavaFX`-Pendant und `implementen` ihr jeweiliges `FrontendSpecific`-Interface. Darüber hinaus implementieren sie nur die nötigen (also im Code tatsächlich genutzten) Konstruktoren, die wiederum nur `super()` aufrufen, hier bspw. [`ToggleButtonGroup`]:
+```java
+public class ToggleButtonGroup extends 
+              com.gluonhq.charm.glisten.control.ToggleButtonGroup 
+                implements FrontendSpecificToggleButtonGroup {
+    public ToggleButtonGroup(){
+        super();
+    }
+
+    public ToggleButtonGroup(ToggleButton... toggles) {
+        super(toggles);
+    }    
+}
+```
+Alle für das Marker-Pattern eingeführten Klassen sind in @uml-marker erkennbar:
+
+::: {#uml-marker}
+
+```{mermaid}
+%%| fig-width: 6.5
+classDiagram
+direction TB
+class FrontendSpecificObject {
+    <<interface>>
+}
+class FrontendSpecificToggleButtonGroup {
+    <<interface>>
+}
+class ToggleButtonGroup {
+    public ToggleButtonGroup()
+    public ToggleButtonGroup(ToggleButton... toggles)
+}
+
+class `com.gluonhq.charm.glisten.control.ToggleButtonGroup` {
+    ...
+    ....()
+}
+
+FrontendSpecificObject <|-- FrontendSpecificToggleButtonGroup : << extends >>
+FrontendSpecificToggleButtonGroup <|-- ToggleButtonGroup : << implements >>
+`com.gluonhq.charm.glisten.control.ToggleButtonGroup` <|-- ToggleButtonGroup : << extends >>
+
+class FrontendSpecificVBox{
+    <<interface>>
+}
+class VBox {
+    public VBox()
+}
+
+class `javafx.scene.layout.VBox` {
+    ...
+    ....()
+}
+
+FrontendSpecificObject <|-- FrontendSpecificVBox : << extends >>
+FrontendSpecificVBox <|-- VBox : << implements >>
+`javafx.scene.layout.VBox` <|-- VBox : << extends >>
+
+class FrontendSpecificCircle {
+    <<interface>>
+}
+class Circle {
+    public Circle()
+}
+
+class `javafx.scene.shape.Circle` {
+    ...
+    ....()
+}
+
+
+FrontendSpecificObject <|-- FrontendSpecificCircle : << extends >>
+FrontendSpecificCircle <|-- Circle : << implements >>
+`javafx.scene.shape.Circle` <|-- Circle : << extends >>
+
+
+```
+
+Das genutzte Marker-Pattern und alle seine Verwendungen
+:::
+## Beobachter- (/Observer-) Entwurfsmuster
+[Beobachter-Entwurfsmuster](https://en.wikipedia.org/wiki/Observer_pattern) werden genutzt, damit ein Subjekt mehrere Beobachter über eine Zustandsänderung informieren kann. In unserem Projekt passiert das bei einer Änderung der `totalExecutionTime`. Das Subjekt `ExecutionTimeSubject` führt hierbei ein `Set` an Beobachtern, die bei uns durch das Interface `ExecutionTimeObserver` repräsentiert werden, welches durch die `registerObserver`- und `unregisterObserver`-Funktionen verwaltet werden kann. Bei einer Zustandsänderung muss die `notifyObservers`-Funktion aufgerufen werden, welche für alle Observer die im Interface spezifizierte `executionTimeChanged`-Funktion aufruft. 
+

src/main/java/fabrik/simulator/pic16f84/Controller_Frontend.java

@@ -1,6 +1,7 @@
 package fabrik.simulator.pic16f84;
 
 
+import fabrik.simulator.pic16f84.frontendspecifics.Circle;
 import fabrik.simulator.pic16f84.frontendspecifics.FrontendSpecificToggleButtonGroup;
 import fabrik.simulator.pic16f84.frontendspecifics.ToggleButtonGroup;
 
@@ -14,7 +15,6 @@ import javafx.fxml.FXML;
 import javafx.scene.Scene;
 import javafx.scene.control.*;
 import javafx.scene.layout.VBox;
-import javafx.scene.shape.Circle;
 import javafx.stage.FileChooser;
 
 import java.io.File;

src/main/java/fabrik/simulator/pic16f84/ExecutionTimeSubject.java

@@ -24,8 +24,8 @@ public abstract class ExecutionTimeSubject extends PICComponent implements PICCo
     }
 
     protected void notifyObservers(){
-            observers.forEach(o -> o.executionTimeChanged());
+        observers.forEach(o -> o.executionTimeChanged());
-        }
+    }
         
     public double getTotalExecutionTime(){
         throw new UnsupportedOperationException("No class implements ExecutionTimeSubject correctly!");

src/main/java/fabrik/simulator/pic16f84/IOPorts.java

@@ -1,5 +1,7 @@
 package fabrik.simulator.pic16f84;
 
+import fabrik.simulator.pic16f84.frontendspecifics.Circle;
+import fabrik.simulator.pic16f84.frontendspecifics.FrontendSpecificCircle;
 import fabrik.simulator.pic16f84.frontendspecifics.FrontendSpecificToggleButtonGroup;
 import fabrik.simulator.pic16f84.frontendspecifics.ToggleButtonGroup;
 import fabrik.simulator.pic16f84.interfaces.*;
@@ -8,7 +10,6 @@ import javafx.scene.control.ToggleButton;
 import javafx.scene.paint.Color;
 import javafx.scene.paint.RadialGradient;
 import javafx.scene.paint.Stop;
-import javafx.scene.shape.Circle;
 
 import java.io.IOException;
 
@@ -187,9 +188,9 @@ public class IOPorts extends PICComponent implements IOPortInterface {
         }
     }
 
-    public void setLEDs (Circle[] a, Circle[] b){
+    public void setLEDs (FrontendSpecificCircle[] a, FrontendSpecificCircle[] b){
-        allLEDsA = a;
+        allLEDsA = (Circle []) a;
-        allLEDsB = b;
+        allLEDsB = (Circle []) b;
     }
 
     public void refreshTable(ToggleButtonGroup parent) {

src/main/java/fabrik/simulator/pic16f84/frontendspecifics/Circle.java

@@ -0,0 +1,8 @@
+package fabrik.simulator.pic16f84.frontendspecifics;
+
+
+public class Circle extends javafx.scene.shape.Circle implements FrontendSpecificCircle {
+    public Circle () {
+        super();
+    }
+}

src/main/java/fabrik/simulator/pic16f84/frontendspecifics/FrontendSpecificCircle.java

@@ -0,0 +1,4 @@
+package fabrik.simulator.pic16f84.frontendspecifics;
+
+public interface FrontendSpecificCircle extends FrontendSpecificObject {
+}

src/main/java/fabrik/simulator/pic16f84/interfaces/CommandInterface.java

@@ -6,7 +6,4 @@ public interface CommandInterface extends PICComponentInterface {
     int get_wRegister();
 
     void decode(int i);
-
-
-
 }

src/main/java/fabrik/simulator/pic16f84/interfaces/IOPortInterface.java

@@ -1,9 +1,8 @@
 package fabrik.simulator.pic16f84.interfaces;
 
-import javafx.scene.shape.Circle;
-
 import java.io.IOException;
 
+import fabrik.simulator.pic16f84.frontendspecifics.FrontendSpecificCircle;
 import fabrik.simulator.pic16f84.frontendspecifics.FrontendSpecificObject;
 import fabrik.simulator.pic16f84.frontendspecifics.FrontendSpecificToggleButtonGroup;
 
@@ -24,7 +23,7 @@ public interface IOPortInterface extends PICComponentInterface, FrontendSpecific
 
     void reset();
 
-    void setLEDs(Circle[] allLEDsA, Circle[] allLEDsB);
+    void setLEDs(FrontendSpecificCircle[] allLEDsA, FrontendSpecificCircle[] allLEDsB);
 
     void setLEDs(boolean[] booleans);
 }

src/main/java/fabrik/simulator/pic16f84/interfaces/TableInterface.java

@@ -1,7 +1,6 @@
 package fabrik.simulator.pic16f84.interfaces;
 
 import fabrik.simulator.pic16f84.frontendspecifics.FrontendSpecificVBox;
-import javafx.scene.layout.VBox;
 
 public interface TableInterface extends PICComponentInterface {
     void refresh();