Faktor-IPS Tutorial

Teil 1: Modellierung und Produktkonfiguration

Definition der Hausratprodukte

In diesem Kapitel definieren wir nun die Produkte „HR-Optimal“ und „HR-Kompakt“ in Faktor- IPS. Hierzu wird die speziell für den Fachbereich entwickelte Produktdefinitionsperspektive verwendet.

Als erstes richten Sie ein neues Projekt mit dem Namen „Hausratprodukte“ und dem Sourceverzeichnis „produktdaten“ ein. Dazu wieder mit Hilfe des Archetype über die Kommandozeile ein neues Maven-Projekt mit der Faktor-IPS Nature erzeugen.

mvn archetype:generate -DarchetypeGroupId=org.faktorips -DarchetypeArtifactId=faktorips-maven-archetype -DarchetypeVersion=24.1.7.release -DgroupId=org.faktorips.tutorial -DartifactId=Hausratprodukte -Dversion=1.0 -Dpackage=org.faktorips.tutorial.produktdaten -DJavaVersion=17 -DIPS-Language=de -DIPS-IsModelProject=false -DIPS-IsProductDefinitionProject=true -DIPS-SourceFolder=produktdaten -DIPS-RuntimeIdPrefix=hausrat. -DIPS-ConfigureIPSBuild=true

Als Typ wählen Sie diesmal Produktdefinitions-Project ("-DIPS-IsProductDefinitionProject=true"), als Packagename „org.faktorips.tutorial.produktdaten“ und als Runtime-ID Prefix „hausrat.“. Achten Sie darauf, dass der Prefix mit einem Punkt (.) endet. Faktor-IPS erzeugt für jeden neuen Produktbaustein eine Id, mit der der Baustein zur Laufzeit identifiziert wird. Standardmäßig setzt sich diese Runtime-ID aus dem Prefix gefolgt von dem (unqualifizierten) Namen zusammen [11]. Der qualifizierte Name eines Bausteines wird nicht zur Identifikation zur Laufzeit verwendet, da die Packagestruktur zur Organisation der Produktdaten zur Entwicklungszeit dient. Auf diese Weise können die Produktdaten umstrukturiert (refactored) werden, ohne dass dies Auswirkungen auf die nutzenden operativen Systeme hat.

11 Für die Implementierung eigener Verfahren zur Vergabe der Runtime-ID wird ein entsprechender Extension Point bereitgestellt werden.

Das Projekt muss anschließend über File ► Import ► Maven ► Existing Maven Projects in den Eclipse Workspace importiert werden.

Faktor-IPS generiert Java Sourcefiles und kopiert XML-Dateien, die zu 100% generiert werden, in das Verzeichnis "src/main/resources". Der Inhalt des Verzeichnisses kann also jederzeit gelöscht und neu erzeugt werden. Da in diesem Ordner im Verlauf dieses Tutorials auch Source-Code für Formeln generiert wird, muss Maven angewiesen werden, diesen auch im "src/main/resources"-Ordner zu bauen. Dazu muss in der pom.xml-Datei unter <plugins> der folgende Code ergänzt werden:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <version>3.2.0</version>
    <executions>
        <execution>
            <id>add-source</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>add-source</goal>
            </goals>
            <configuration>
                <sources>
                    <source>${project.basedir}/src/main/resources</source>
                </sources>
            </configuration>
        </execution>
    </executions>
</plugin>

Die Verwaltung der Produktdaten in einem eigenen Projekt erfolgt vor dem Hintergrund, dass die Verantwortung für die Produktdaten bei anderen Personen liegt und sie auch einen anderen Releasezyklus haben können. So könnte die Fachabteilung zum Beispiel ein neues Produkt „HR-Flexibel“ erstellen und freigeben, ohne dass das Modell geändert wird. Damit in dem neuen Projekt auf die Klassen des Hausratmodells zugegriffen werden kann, muss in Faktor -IPS im Produktdatenprojekt eine Referenz auf das Hausratmodell-Projekt definiert werden. Das funktioniert in Faktor-IPS analog zur Definition des Build Path in Java. Damit auch die Javaklassen in dem Projekt verfügbar sind, muss die pom.xml-Datei des Projekts „Hausratprodukte“ um eine Abhängigkeit zum Projekt „Hausratmodell“ ergänzt werden. Dazu fügen Sie einfach unter <dependencies> in der pom.xml-Datei den folgenden Eintrag hinzu:

<dependency>
    <groupId>org.faktorips.tutorial</groupId>
    <artifactId>Hausratmodell</artifactId>
    <version>1.0</version>
</dependency>

Anschließend müssen noch die JUnit 5 Bibliotheken zu dem Projekt hinzugefügt werden, da wir später eine Testklasse schreiben werden. Dazu ergänzen Sie in der pom.xml-Datei die folgenden Abhängigkeiten:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.9.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-runner</artifactId>
    <version>1.9.0</version>
    <scope>test</scope>
</dependency>

Falls wie im Archetype vorgeschlagen Java 17 genutzt wurde, muss die folgende Abhängigkeit ergänzt werden:

<dependency>
    <groupId>jakarta.xml.bind</groupId>
    <artifactId>jakarta.xml.bind-api</artifactId>
    <version>4.0.0</version>
</dependency>

Damit die Änderungen in der pom.xml-Datei wirksam werden, führen Sie einen Rechtklick auf das Projekt „Hausratprodukte“ aus und wählen Maven ► Update Project ► Ok.

Öffnen Sie nun zunächst die Produktdefinitionsperspektive über Window ► Perspective ► Open Perspective ► Other ► Produktdefintion auswählen [12]. Falls Sie noch Editoren geöffnet haben, schließen Sie diese jetzt, um die Sichtweise der Fachabteilung auf das System zu haben. Damit Sie im Problems-View ausschließlich die Marker von Faktor-IPS sehen (und nicht auch Java-Marker u.a.) müssen Sie im Problems-View den Faktor-IPS Filter ein- und alle anderen Filter (standardmäßig mindestens der Defaultfilter) ausschalten.

12 Für die Verwendung von Faktor-IPS durch die Fachabteilung gibt es auch eine eigene Installation (in Eclipse Terminologie: ein eigenes Produkt), bei der ausschließlich die Produktdefinitionsperspektive verfügbar ist.

Zunächst legen wir zwei IPS-Packages an, eines für die Produkte und eines für die Deckungen. Dies geschieht wie in der Java Perspektive entweder über das Kontextmenü oder die Toolbar (als Quellordner „Hausratprodukte“ wählen).

Figure 1. Anlegen zweier IPS Packages

Bemerkung: Sie können in dem Projekt beliebig viele Verzeichnisse anlegen. Zum Beispiel ein doc- Verzeichnis zur Verwaltung von Produktdokumenten.

Als erstes legen wir jetzt das Produkt „HR-Optimal“ an. Markieren Sie dazu das gerade angelegte Package „produkte“ und klicken dann in der Toolbar NewProductCmptWizard an . Es öffnet sich der Wizard zum Erzeugen eines neuen Produktbausteins. Der Wizard bietet Ihnen nun die im Modell verfügbaren Produktklassen zur Auswahl, zu denen Sie Produktbausteine erstellen können. Wählen Sie HausratProdukt.

Figure 2. Auswahl der Produktbaustein-Klasse

Falls Sie keine Produktklasse finden, fehlt noch die Referenz auf das Hausratmodell-Projekt im Faktor-IPS Build Path (s.o.). Gehen Sie mit Next zur nächsten Seite des Wizards.

Hier geben Sie den Namen des Bausteins ein. Wenn Sie nun Finish drücken wird der Produktbaustein im Dateisystem angelegt.

Figure 3. Anlegen eines neuen Produkts

Mit Doppelklick auf den Produktbaustein im Produktdefinitions-Explorer öffnen Sie den Editor für den Baustein.

Figure 4. Produktbaustein-Editor für HR-Optimal

Die erste Seite des Editors zeigt:

Eigenschaften
Enthält die Eigenschaften der Anpassungsstufe. Hier ist jedes in der Produktklasse definierte Attribut aufgelistet.
Vorbelegungen und Wertebereiche
Enthält die Vorbelegungswerte und Wertebereiche für die Vertragseigenschaften.
Beziehungen
Enthält die verwendeten anderen Produktbausteine.

Geben Sie Daten für das Produkt HR-Optimal entsprechend der folgenden Tabelle ein:

Konfigurationsmöglichkeit	HR-Optimal
Produktname	Hausrat Optimal
Vorschlag Versicherungssumme pro qm Wohnfläche	900 EUR
Vorgabewert Zahlweise	1 (jährlich)
Erlaubte Zahlweisen	1, 2, 4, 12
Vorgabewert Wohnflaeche	<keine Vorbelegung>
Erlaubte Wohnflaeche	0-2000
Vorgabewert Versicherungssumme	<keine Vorbelegung>
Versicherungssumme	10000 EUR - 5000000 EUR

Konfigurationsmöglichkeit

HR-Optimal

Produktname

Hausrat Optimal

Vorschlag Versicherungssumme pro qm Wohnfläche

900 EUR

Vorgabewert Zahlweise

1 (jährlich)

Erlaubte Zahlweisen

1, 2, 4, 12

Vorgabewert Wohnflaeche

Erlaubte Wohnflaeche

0-2000

Vorgabewert Versicherungssumme

Versicherungssumme

10000 EUR - 5000000 EUR

Beim Anlegen des Produktbausteins haben Sie folgende Fehlermeldung bekommen:

Figure 5. Fehlermeldung beim Anlegen des Produktbausteins

Um diese zu beheben, legen wir nun den Grunddeckungstyp für das Produkt an. Markieren Sie hierzu den Ordner Deckungen und legen einen neuen Produktbaustein mit Namen „HRD-Grunddeckung-Optimal“ an basierend auf der Klasse „HausratGrunddeckungstyp“.

Nun müssen wir noch den Deckungstyp dem Produkt „HR-Optimal“ zuordnen. Dies kann man bequem per Drag&Drop aus dem Produktdefinitions-Explorer erledigen. Öffnen Sie das Produkt „HR-Optimal“. Ziehen Sie die „HRD-Grunddeckung-Optimal“ aus dem Explorer auf den Knoten HausratGrundeckungstyp im Bereich Beziehungen.

Figure 6. Zuordnung von Deckungstypen zu einem Produkt

Unter „Art der Beziehung“ muss Obligatorisch gewählt werden, da es sich um eine 1..1(1) Relation handelt. (Grund dafür ist die definierte Beziehung zwischen „HausratProdukt“ und „HausratGrunddeckungstyp“. Siehe Abbildung 25)

Im nächsten Schritt legen wir das Produkt „HR-Kompakt“ inklusive der Grunddeckung „HRD-GrunddeckungKompakt“ an. Dies können Sie analog zum Produkt „HR-Optimal“ machen. Alternativ können Sie einen Kopierassistenten verwenden, mit dem Sie einen Produktbaustein inklusive aller verwendeter Bausteine kopieren können. Wenn Sie dies ausprobieren möchten, markieren Sie das Produkt „HR-Optimal“ im Produktdefinitions-Explorer und wählen im Kontextmenü New ► Copy Product …

Im geöffneten Dialog geben Sie als Search Pattern (Suchen nach) „Optimal“ und als Replace Pattern (Ersetzen durch) „Kompakt“ ein, klicken Next und dann Finish. Faktor-IPS legt die Bausteine „HR-Kompakt“ und „HRD-Grunddeckung“ neu an. Öffnen Sie „HR-Kompakt“ und geben Sie Daten entsprechend der nachfolgenden Tabelle ein:

Konfigurationsmöglichkeit	HR-Kompakt
Produktname	Hausrat Kompakt
Vorschlag Versicherungssumme pro qm Wohnfläche	600 EUR
Vorgabewert Zahlweise	jährlich
Erlaubte Zahlweisen	halbjährlich, jährlich
Vorgabewert Wohnflaeche	<keine Vorbelegung>
Erlaubte Wohnflaeche	0-1000 qm
Vorgabewert Versicherungssumme	<keine Vorbelegung>
Versicherungssumme	10000 EUR - 2000000 EUR

Konfigurationsmöglichkeit

HR-Kompakt

Produktname

Hausrat Kompakt

Vorschlag Versicherungssumme pro qm Wohnfläche

600 EUR

Vorgabewert Zahlweise

jährlich

Erlaubte Zahlweisen

halbjährlich, jährlich

Vorgabewert Wohnflaeche

Erlaubte Wohnflaeche

0-1000 qm

Vorgabewert Versicherungssumme

Versicherungssumme

10000 EUR - 2000000 EUR

Damit ist die Definition der beiden Produkte zunächst abgeschlossen. Im Produktdefinitions-Explorer sollten Sie folgendes sehen.

Figure 7. Darstellung der Produkte im Produktdefinitions-Explorer

Neben dem Produktdefinitions-Explorer stehen Ihnen zwei weitere Werkzeuge zur Analyse der Produktdefinition zur Verfügung. Die Struktur eines Produktes können Sie sich mit Show Structure im Kontextmenü anzeigen lassen. Die unterschiedliche Verwendung eines Bausteins mit Search References. Darüber hinaus können Sie die Reihenfolge der Pakete über den Menüpunkt Edit Sort Order frei festlegen.

Rechts neben dem Editor zur Eingabe der Produktdaten befindet sich der Model Description View. Dieser zeigt passend zum in Bearbeitung befindlichen Produktbaustein die Dokumentation der zugehörigen Produktklasse. Wenn Sie die einmal ausprobieren wollen, dokumentieren Sie z.B. das Attribut produktname im Modell, schließen Sie den Bausteineditor und öffnen ihn erneut.