Faktor-IPS Produktdaten in der Datenbank

Deployment der Produktdaten

Client

Der ProductDataDeploymentClient wird über einen Builder mit folgenden Informationen erstellt:

  • ReadonlyTableOfContents

  • Name

  • Modell-Version

  • Produkt-Version (siehe Versionierung)

Er bietet Methoden an, die die REST-API aufrufen um zum Beispiel eine neue ToC Version anzulegen und alle darin aufgelistete Produkte, Tabellen und Enums einzuspielen.

Builder

Der Builder für den ProductDataDeploymentClient wird über die Methode ProductDataDeploymentClient.Builder.forApi(WebTarget) erstellt. Mittels diverser with~-Methoden kann die zukünftige Client-Instanz konfiguriert werden. Durch den Aufruf von build() wird die Client-Instanz erzeugt und kann dann verwendet werden. Im Folgenden werden die einzelnen with~-Methoden erläutert.

Dieses Muster wird "Builder-Pattern" genannt. Die with~-Methoden geben jeweils ein neues Builder-Objekt zurück, um den Aufruf im Stil einer Fluent API zu erlauben und teilweise konfigurierte Builder-Instanzen wiederverwenden zu können.
withTocPath

Konfiguriert den Pfad zu einer Table-of-Contents-Datei auf dem Classpath, mit dem der Builder gestartet wurde. Dieser Parameter muss konfiguriert werden, wenn der Client zum Einspielen von Produktdaten verwendet wird. Aus dem angegebenen ToC werden dann die einzuspielenden Produkte, Tabellen und Enums gelesen. Falls der Client zum Ändern des Status oder Löschen einer Produktdaten-Version eingesetzt wird, muss dieser nicht angegeben werden.

Wenn tocPath konfiguriert ist, kann die Produktversion automatisch aus dem ToC ausgelesen werden. Auch das Auslesen der Modell-Version ist möglich. Dazu muss einerseits zur <toc-name>.xml-Datei eine <toc-name>.model.properties-Datei vorhanden sein, andererseits die darin benannten Modell-ToCs auf dem Classpath verfügbar sein (siehe Modell-Versionen).

withTocName

Der Name für das Produktdatenprojekt. Muss immer konfiguriert werden. Der tocName entspricht dem Namen der xml-Datei, die das ToC enthält.

withModelVersion

Die Modell-Version. Kann weggelassen werden, wenn der tocPath angegeben ist und der Versionsstring damit automatisch erstellt wird (siehe Modell-Versionen).

Für das Löschen sowie Statusupdate von mehreren ToC Versionen kann ein Leerstring oder * als Wildcard angegeben werden.

withVersion

Die Produktdaten-Version. Kann weggelassen werden, wenn der tocPath angegeben ist und damit die im Table of Contents gespeicherte Versionsnummer verwendet wird.

Für das Löschen sowie Statusupdate von mehreren ToC Versionen kann ein Leerstring oder * als Wildcard angegeben werden.

withAuthentication

Benutzername und Passwort für den Zugriff auf die REST-API. Im Application Server muss der Benutzer mit der Rolle ipsdeploy eingetragen sein.

Logging und Fehlerbehandlung

Über die Methoden withSuccessHandler und withFailureHandler können einem Client Handler für das Logging von Deployment-Fortschritt und -Fehlern mitgegeben werden. Werden keine Handler explizit gesetzt, wird auf System.out geloggt und Fehlermeldungen auf System.err ausgegeben.

Ist einer der benötigten Parameter nicht gesetzt, wirft der Builder eine MissingArgumentException.

Modell-Versionen

Wird dem Client-Builder nicht manuell eine Modell-Version mitgegeben, versucht er diese automatisch zu erstellen. Dazu sucht er parallel zum Produkt-ToC in <toc-path>.xml eine Datei <toc-path>.model.properties. In dieser sind Pfade zu ebenfalls auf dem Classpath liegenden Modell-ToCs abgelegt, aus denen wiederum die Versionsnummern ausgelesen werden.

Beruht das Produktprojekt direkt auf einem einzelnen Modellprojekt, hat die Property das folgende Format:

modelToc=org/faktorips/sample/model/internal/faktorips-repository-toc.xml

Die Modellversion wird dann direkt aus dem Attribut productDataVersion des Tags FaktorIps-TableOfContents ausgelesen, wohin sie beim Bauen des Modellprojekts aus dem Tag Version der .ipsproject-Datei kopiert wurde.

Beruht das Produktprojekt direkt auf einem mehreren Modellprojekten können diese mit Namen und einer Reihenfolge versehen werden:

modelToc.1.base=org/faktorips/sample/model/internal/faktorips-repository-toc.xml
modelToc.2.lob=org/faktorips/sample/lob/model/internal/faktorips-lob-repository-toc.xml

Verwendung

Der Client bietet mehrere Methoden, die nacheinander aufgerufen werden können, um Produktdaten einzuspielen, aktiv zu schalten und ggf. wieder zu löschen. Jede Methode gibt zurück, ob das anlegen geklappt hat und loggt zusätzlich über die Success- und FailureHandler weitere von der REST-API zurückgegebene Informationen.

createTocVersion

Legt eine neue Table-of-Contents-Version in der Datenbank an. Dabei werden die bei der Erstellung des Clients angegebenen Versionsparameter genutzt. Optional können die Parameter user und comment angegeben werden: user, um in der Datenbank sehen zu können, wer eine bestimmte Version angelegt hat; comment, um die Version mit einem Kommentar zu versehen..

deployProducts

Spielt alle Produkte aus dem Table of Contents ein. Schlägt das Einspielen eines Produktbausteins fehl, bricht die Methode sofort ab.

deployTables

Spielt alle Tabelleninhalte aus dem Table of Contents ein. Schlägt das Einspielen eines Tabelleninhalts fehl, bricht die Methode sofort ab.

deployEnums

Spielt alle Aufzählungsinhalte aus dem Table of Contents ein. Schlägt das Einspielen eines Aufzählungsinhalts fehl, bricht die Methode sofort ab.

updateStatus

Ändert den Status einer Table-of-Contents-Version. Dazu sind vier Status-Übergänge definiert, von denen einer als Parameter übergeben werden muss:

  • COMPLETE setzt eine Version vom Status PENDING auf DEPLOYED. Dieser Status-Übergang wird intern am Ende eines Deployments durchgeführt.

  • ACTIVATE setzt eine Version vom Status DEPLOYED auf ACTIVE. Eine eventuell zuvor aktive Version (mit gleicher Modell-Version und ToC-Namen) erhält den Status HISTORIC.

  • DEACTIVATE setzt eine Version vom Status ACTIVE auf HISTORIC. Dadurch ist dann keine Version mehr aktiv, was zu Fehlern zur Laufzeit führen kann.

  • REACTIVATE setzt eine Version vom Status HISTORIC auf ACTIVE. Eine eventuell zuvor aktive Version (mit gleicher Modell-Version und ToC-Namen) erhält den Status HISTORIC.

Der neue Status wird zurückgegeben, wenn der Statuswechsel funktioniert hat. Ging etwas schief, weil z.B. die Version nicht den passenden Ausgangszustand hat, wird ein leerer Optional-Wert zurückgegeben.

Wird eine Wildcard ("*") als Modellversion oder Produktdatenversion angegeben, so werden alle ToC Versionen selektiert, die die angegebenen Kriterien erfüllen und einen zum Statusübergang passenden Status haben. Das Statusupdate wird nur dann ausgeführt, wenn es genau eine solche ToC Version gibt.

delete

Löscht Table-of-Contents-Versionen mit allen zugehörigen Produkten, Tabellen- und Aufzählungsinhalten. Falls eine Wildcard als Modell-/Produktversion angegeben wird, werden alle passende Table-of-Contents-Versionen, die nicht den Status ACTIVE haben, gelöscht. Optional kann ein Status als Parameter angegeben werden. In dem Fall werden alle Table-of-Contents-Versionen, die sich in diesem Status befinden, gelöscht.

Wird eine Wildcard ("*") als Modellversion oder Produktdatenversion angegeben, so werden alle ToC Versionen gelöscht, die die angegebenen Kriterien erfüllen. Aktive ToC Versionen können nicht gelöscht werden.