Projektmigrationen erweitern

Da Faktor-IPS ständig weiter entwickelt wird, ist bei einem Versionswechsel oft auch eine Migration der bestehenden Projekte notwendig. Zu diesem Zweck kann im Kontextmenü eines Projekts die Migration aufgerufen werden.

Ob eine Migration notwendig ist, wird mit Hilfe der .ipsproject-Datei gesteuert. Darin ist hinterlegt, für welche Version das Projekt aktuell konfiguriert ist. Wenn in einer neuen Faktor-IPS-Version eine Migrationsstrategie für diese neue Version vorhanden ist, muss diese aufgerufen werden, da sonst das einwandfreie Funktionieren der Projekte nicht gewährleistet ist.

Mit einem eigenen Plugin kann das Faktor-IPS-Migrationsframework um eigene Migrationsstrategien erweitert werden. Diese Migrationen können z.B. dazu verwendet werden, um Produktprojekte auf eine neue Modellversion zu migrieren. Beispielsweise könnte eine Produktmigration notwendig werden, wenn im Modell ein neues Attribut eingeführt wurde und in den bestehenden Produkten abhängig von bestimmten Faktoren unterschiedliche initial andere Werte eingestellt werden sollen.

Vorbereitungen

Um eine eigene Migration entwickeln zu können, muss ein eigenes Eclipse-Plugin entwickelt und ausgeliefert werden. Das Plugin benötigt mindestens eine Abhängigkeit auf das Faktor-IPS Core Plug-Inorg.faktorips.devtools.core.

Überblick Architektur

Für eine eigene Migration wird zunächst ein Versionsmanager benötigt. Dieser wird einmal implementiert und legt fest, für welche Feature-ID Migrationen vorhanden sind. Für jeden Versionsmanager wird es in der.ipsproject-Datei einen Eintrag geben, der festlegt, welche Version dieses Features aktuell verwendet wird.

Ein Versionsmanager verwaltet mehrere Migrationsstrategien. Eine Migrationsstrategie ist immer für die Migration von einer Version auf die nächste zuständig. Will man über mehrere Versionen gleichzeitig migrieren, werden alle notwendigen Migrationsstrategien der Reihe nach ausgeführt.

Versionsmanager

Wenn kein eigener Versionsmanager entwickelt werden soll, kann einfach der ExtendableVersionManager verwendet werden. Dieser spezielle Versionsmanager verwendet einfach alle Migrationen, die unter dem Extension Point org.faktorips.devtools.core.ipsMigrationOperation im gleichen Plugin registriert sind. Außerdem wird die für die Migration zu Grunde gelegte Version aus dem Plugin verwendet.

Folgender Eintrag ist in der plugin.xml-Datei notwendig:

<extension point="org.faktorips.devtools.core.faktorIpsFeatureVersionManager">
    <faktorIpsFeatureVersionManager
          class="org.faktorips.devtools.core.model.versionmanager.ExtendableVersionManager"
          featureId="<feature Id>"
          id="<Id des Versionsmanager>"
          requiredForAllProjects="true">
    </faktorIpsFeatureVersionManager>
</extension>

Unter dem Attribut requiredForAllProjects kann eingestellt werden, ob alle Projekte im Workspace die Feature-ID und die Version eingetragen haben müssen. Ist dieses Attribute auf „false“ gesetzt, wird kein Fehler angezeigt, wenn der Eintrag für dieses Feature fehlt.

Bemerkung: In der Version 3.9.0 ist zusätzlich das Attribut ‚basedOnFeatureManager‘ zu füllen. Da hier meist kein sinnvoller Wert einzutragen ist, kann ein beliebiger Wert eingetragen werden. Der Fehler wurde in 3.10 behoben.

Migrationsoperation

Wurde der ExtendableVersionManager verwendet, können Migrationen über org.faktorips.devtools.core.ipsMigrationOperation registriert werden. Der Versionsmanager wird alle Migrationen verwenden, die im gleichen Plugin registriert wurden.

Eine einzelne Migrationsoperation muss auf jeden Fall von der abstrakten Klasse AbstractIpsProjectMigrationOperation abgeleitet werden. Hilfreich sind auch die weiteren abstrakten Basisklassen, vor allem DefaultMigration.

Zur Registrierung in der plugin.xml-Datei muss außerdem eine Factory implementiert werden, die vom Interface IIpsProjectMigrationOperationFactory ableitet. Die Factory kann z.B. als innere Klasse in der eigentlichen Migration angelegt werden.

Im folgenden Ausschnitt aus der plugin.xml-Datei wird gezeigt, wie die Migration für Faktor-IPS 3.2.0 registriert wurde.

 <extension point="org.faktorips.devtools.core.ipsMigrationOperation">
    <migrationOperation
          class="org.faktorips.devtools.core.internal.migrationextensions.Migration_3_2_0$Factory"
          targetVersion="3.2.0">
 </extension>

Wird die DefaultMigration verwendet, muss lediglich die Methode migrate(IIpsSrcFile srcFile) überschrieben werden. Diese Methode wird für jedes IIpsSrcFile einmal aufgerufen. Innerhalb der Methode können beliebige Änderungen an dem IpsObject in dem Sourcefile vorgenommen werden. Änderungen am Objekt dürfen nicht selbst gespeichert werden. Das Migrationsframework wird die Datei zum richtigen Zeitpunkt schreiben.

Utils

Als weitere nützliche Hilfe bietet sich die ManifestUtil-Klasse an. Hier können beispielsweise die Versionen für abhängige Plugin-Versionen im MANIFEST.MF des zu migrierenden Projekts angepasst werden.