Änderungen von Dokument Plugin-Entwicklung

Von 6.1 nach 5.10 Von 12.1 nach 11.1

Von Version 11.1

bearbeitet von awa
am 04.12.2022, 00:41

Änderungskommentar: Uploaded new attachment "pom.xml", version 1.8

Auf Version 6.1

bearbeitet von awa
am 25.02.2022, 13:40

Änderungskommentar: Neuen Anhang pom.xml hochladen

Rohform
Im Layout

Zusammenfassung

Seiteneigenschaften (1 geändert, 0 hinzugefügt, 0 gelöscht)
Anhänge (1 geändert, 0 hinzugefügt, 0 gelöscht)
- pom.xml

Details

Seiteneigenschaften

Inhalt

@@ -5,13 +5,13 @@
  == API-Dokumentation ==
--Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[JavaScript und JavaDocs>>https://docs.formcycle.eu/]]
++Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[Javadocs>>https://docs.formcycle.eu/]]
  == Maven-Setup ==
--Zu Beginn der Entwicklung eines Plugins ist es nötig, das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
++Zu Beginn der Entwicklung eines Plugins ist es nötig das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
--Für letzteres empfehlen wir hierbei das Build-Management-Tool [[Apache Maven>>url:https://maven.apache.org/||rel="__blank"]] zu verwenden. Andere Build-Tools können prinzipiell auch genutzt werden, hier können wir aber keine Hilfe bereitstellen.
++Für letzteres empfehlen wir hierbei das Build-Management-Tool [[Apache Maven>>url:https://maven.apache.org/||rel="__blank"]] zum Einsatz. Andere Build-Tools können prinzipiell benutzt werden, hier können wir aber keine Hilfe bereitstellen.
  Um die entsprechenden Abhängigkeiten zu {{formcycle case="dat"/}} bereitzustellen, ist das Repository unter der URL [[https:~~/~~/artifactory.xima-services.de/artifactory/fc-plugin-dev>>url:https://artifactory.xima-services.de/artifactory/fc-plugin-dev]] zu benutzen. Dieses enthält alle öffentlich zur Verfügung stehenden Artefakte, welche dem Plugin zur Laufzeit bereitgestellt und während der Entwicklung benötigt werden.
@@ -65,25 +65,23 @@
  {{/code}}
  {{/panel}}
--== Maven-Projekteinrichtung ==
++== Maven-Projekteinrichtung
  Im Folgenden werden einige Punkte beschrieben, die beim Einrichten eines Maven-Projekts für ein {{formcycle/}}-Plugin beachtet werden müssen. Für den schnellen Einstieg gibt auch einige [[Maven-Archetypes>>||anchor="HMaven-Archetypes"]].
--=== Artekfakte und Abhängigkeiten ===
++=== Artekfakte und Abhängigkeiten
  {{info}}
  Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
  {{/info}}
--Eine fertige einfache //pom.xml// können Sie [[hier herunterladen>>attach:pom.xml||rel="__blank"]].
++Ausgangspunkt für die Entwicklung von Plugin ist das Maven-Artefakt //fc-plugin-common//. Dieses enthält die einzelnen Plugin-Schnittstellen und steht auch auf [[unserere Downloadseite zur Verfügung>>url:http://artifactory.xima-services.de/artifactory/fc-plugin-dev/de/xima/fc/fc-plugin-common||target="_blank"]].
--Ausgangspunkt für die Entwicklung von Plugin ist das Maven-Artefakt //fc-plugin-common//. Dieses enthält die einzelnen Plugin-Schnittstellen und steht auch auf [[unsererer Downloadseite zur Verfügung>>url:http://artifactory.xima-services.de/artifactory/fc-plugin-dev/de/xima/fc/fc-plugin-common||rel="noopener noreferrer" target="_blank"]].
--
  In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:
  {{code language="xml"}}
    <properties>
--    <xfc.version>7.2.1</xfc.version>
++    <xfc.version>7.0.10</xfc.version>
    </properties>
    <dependencies>
@@ -96,7 +96,7 @@
    </dependencies>
  {{/code}}
--Ferner steht je nach Tiefe der Integration in die bestehende Umgebung von {{formcycle case="dat"/}} und deren Benutzung als höchste Implementierung das Artefakt //fc-logic// zur Verfügung. Dieses wird wie folgt als weitere (oder einzige) Abhängigkeit definiert:
++Ferner steht je nach Tiefe der Integration in die bestehende Umgebung von {{formcycle case="dat"/}} und dessen Benutzung als höchste Implementierung das Artefakt //fc-logic// zur Verfügung. Dieses wird wie folgt als weitere (oder einzige) Abhängigkeit definiert:
  {{code language="xml"}}
    <dependency>
@@ -107,44 +107,23 @@
    </dependency>
  {{/code}}
--Eine entsprechende Benutzung ist vor allem bei der Verwendung der Datenbankschnittstelle sowie bei der Implementierung von eigenen Verarbeitungen nötig.
++Eine entsprechende Benutzung ist vor allem bei der Verwendung der Datenbankschnittstelle sowie bei der Implementierung von eigenen Verarbeitungen nötig. Eine Vorlage für ein somit entstehendes Project Object Model finden Sie [[hier>>attach:pom.xml||rel="__blank"]].
--Ferner ist zu beachten, dass sämtliche Abhängigkeiten zu {{formcycle case="dat"/}} im scope //provided //anzugeben sind. Dies verhindert neben Classpath-Problemen auch das unnötige Anschwellen der Plugin-Größe. Ebenso sollten diesbezüglich Abhängigkeiten auf bereits von {{formcycle case="dat"/}} benutzten und damit bereitstehenden Bibliotheken wiederverwendet werden (z.B. diverse Apache Commons-Implementierungen). Solche Abhängigkeit sind auch im Scope //provided// zu definieren. Eine einfache Möglichkeit, Fehler zu vermeiden, ist das Importieren der FORMCYCLE-Bom:
++Ferner ist zu beachten, dass sämtliche Abhängigkeiten zu {{formcycle case="dat"/}} im scope //provided //anzugeben sind. Dies verhindert neben Classpath-Problemen auch das unnötige Anschwellen der Plugin-Größe. Ebenso sollten diesbezüglich Abhängigkeiten auf bereits von {{formcycle case="dat"/}} benutzten und damit bereitstehenden Bibliotheken wiederverwendet werden (z.B. diverse Apache Commons-Implementierungen).
--{{code language="xml"}}
--	<dependencyManagement>
--		<dependencies>
--			<!--Import dependency versions from FORMCYCLE -->
--			<dependency>
--				<groupId>de.xima.fc</groupId>
--				<artifactId>fc</artifactId>
--				<version>${xfc.version}</version>
--				<type>pom</type>
--				<scope>import</scope>
--			</dependency>
--		</dependencies>
--	</dependencyManagement>
--{{/code}}
++=== Manifest und Fat JAR
--Dann einfach die gewünschte Abhängigkeit ohne {{code}}<version>...</version>{{/code}} definieren. Wenn FORMCYCLE die Abhängigkeit schon enthält, gibt es keinen Build-Fehler. Andernfalls muss diese im Plugin mitgeliefert werden. In dem Fall die Version hinzufügen und den Provided-Scope entfernen.
--
--=== Manifest und Fat JAR ===
--
  In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
  ; formcycle-version-requirement
--: Erforderlich. Version von {{formcycle/}}, für die das Plugin gedacht ist. Ist erforderlich, damit {{formcycle/}} bei der Installation die Kompatibilität prüfen kann.
++: Erforderlich. Version von {{formcycle/}}, für die das Plugin gedacht ist.Ist erforderlich, damit {{formcycle/}} bei der Installation die Kompatibilität prüfen kann.
  ; Implementation-Version
--: Erforderlich. Version des Plugins; Diese wird z.B. in der Oberfläche angezeigt.
--; Plugin-Key
--: Erforderlch. Wird zur Identifizierung des Plugin innherhalb von {{formcycle/}} verwendet, und auch von etwa dem Deploy-Plugin oder Server-Plugin. Empfohlener Wert ist {{code}}${project.groupId}:${project.artifactId}{{/code}}.
++: Erforderlich. Version des Plugins, wird etwa in der Oberfläche angezeigt.
  ; Build-Time oder Build-Timestamp
--: Optional. Wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren.
++: Optional, wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren.
++; Implementation-Title
++: Optional, wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren.
--{{info}}
--Bis einschließlich Version 7.x von {{formcycle/}} ist noch {{code}}Implementation-Title{{/code}} mit dem gleichen Wert wie {{code}}Plugin-Key{{/code}} erforderlich.
--{{/info}}
--
  Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden.
  Weiterhin ist beim Bauen zu beachten, dass eine sogenannte Fat-JAR gebaut werden muss. Abhängigkeiten zu {{formcycle case="dat"/}} sowie anderen Bibliotheken, welche bereits durch {{formcycle case="acc"/}} mitgeliefert werden, sollten wie bereits erwähnt im scope //provided// eingebunden werden. Falls im Plugin aber noch andere Abhängigkeiten benutzt werden, müssen diese in der JAR-Datei inkludiert werden (Fat JAR).
@@ -223,7 +223,7 @@
    Auswahl eines Archetypes beim Erstellen eines Maven-Projekts in Eclipse
  {{/figure}}
--Für einige häufig verwendete Plugin-Typen stehen [[Maven-Archetypes>>url:https://maven.apache.org/guides/introduction/introduction-to-archetypes.html||rel="noopener noreferrer" target="_blank"]] bereits, um schnell ein Maven-Projekt aufsetzen zu können.
++Für einige häufig verwendete Plugin-Typen stehen [[Maven-Archetypes>>url:https://maven.apache.org/guides/introduction/introduction-to-archetypes.html||target="_blank"]] bereits, um schnell ein Maven-Projekt aufsetzen zu können.
  Voraussetzung für die Verwendung ist, dass in den //~~/.m2/settings.xml// wie oben beschrieben das XIMA-Artifactory eingerichtet wurde. Dann kann etwa über die Kommandozeile wie folgt eine Archetype generiert werden:
@@ -233,15 +233,13 @@
  Es werden dann einige wenige Informationen wie die gewünschten Maven-Koordinaten des neuen Plugin-Projekts abgefragt und anschließend ein neues vorkonfiguriertes Projekt erstellt.
--Alle vorhandenen Archetypes und deren Versionen können im [[Archetype-Katalog>>url:https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml||rel="noopener noreferrer" target="_blank"]] eingesehen werden.
++Alle vorhandenen Archetypes und deren Versionen können im [[Archetype-Katalog>>url:https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml||target="_blank"]] eingesehen werden.
  In Eclipse kann der Archetype-Katalog in den Einstellungen hinzugefügt werden. Bei der Erstellung eines neuen Maven-Projekt werden dann alle verfügbaren Archetypes angezeigt:
--{{code language="plaintext"}}
--https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml
--{{/code}}
++{{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}}
--== Deploy-Plugin ==
++== Deploy-Plugin
  Um beim Entwickeln nicht jedes Mal eine neue Plugin-Version manuell über die Oberfläche hochladen zu müssen, kann das Deploy-Plugin verwendet werden. Dieses besteht aus 2 Teilen:
@@ -248,40 +248,39 @@
  * Ein Maven-Plugin, welches nach dem Bauen das Plugin via HTTP an einen laufenden {{formcycle/}}-Server sendet
  * Ein Plugin für {{formcycle/}}, welche die Gegenstelle in {{formcycle/}} bereitstellt und das Plugin aus dem HTTP-Request in {{formcycle/}} installiert.
--Weitere Details können im [[Hilfe-Artikel zum Deploy-Plugin>>doc:Formcycle.PluginDocumentation.FormcycleDeployPluginPlugin]] nachgelesen werden. Für die meisten Fälle ist kene Konfiguration in der //pom.xml// erforderlich. Es empfiehlt sich aber, wenigstens die Version festzusetzen:
++Weitere Details können im [[Hilfe-Artikel zum Deploy-Plugin>>doc:Formcycle.PluginDocumentation.FormcycleDeployPluginPlugin]] nachgelesen werden. Für die meisten Fälle reicht folgende Konfiguration in der //pom.xml// des Plugin-Projekts aus:
  {{code language="xml"}}
    <properties>
--    <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version></fc-deploy-plugin-maven-plugin>
++    <fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version/>
    <build>
      <plugins>
--   <plugin>
++	  <plugin>
          <groupId>de.xima.fc.maven.plugin</groupId>
          <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
          <version>${fc-deploy-plugin-maven-plugin.version}</version>
++        <executions>
++          <execution>
++            <id>upload</id>
++            <phase>install</phase>
++            <goals>
++              <goal>deploy</goal>
++            </goals>
++          </execution>
++        </executions>
        </plugin>
      </plugins>
    </build>
  {{/code}}
--Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann wie folgt gebaut und hochgeladen werden:
++Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann beim Bauen wie folgt hochgeladen werden:
  {{code language="bash"}}
--mvn fc-deploy:deploy
++mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
  {{/code}}
--Es wird hierbei davon ausgegangen, dass {{formcycle/}} unter der Standard-URL {{code}}http://localhost:8080/xima-formcycle{{/code}} läuft und das Standard-Passwort "admin" für das Deploy-Plugin verwendet wird. Ist dies nicht der Fall, können die Werte auch angepasst werden:
++Wird Eclipse benutzt, kann auch eine Launch-Configuration mit den //fcDeployUrl// und dem //fcDeployToken// angelegt werden.
--{{code language="bash"}}
--mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
--{{/code}}
--
--{{info}}
--Bis einschließlich Version 7.x von {{formcycle/}} und dem Maven-Plugin ist es noch erforderlich, die package-Phase explizit aufzuführen. Zudem müssen die URL und das Passwort angegeben werden. Ab Version 8.x sind die Standardwerte gesetzt und die package-Phase wird automatisch ausgeführt.
--{{/info}}
--
--Soll das Plugin im Bereich eines bestimmten Mandanten registriert werden, so kann dies über den zusätzlichen Launch-Configuration Parameter //fcDeployClientId //erreicht werden. Dieser Parameter muss als Wert die Id des Mandanten enthalten.
--
  == FC-Server-Plugin ==
  Zum Testen eines Plugins ist es erforderlich, einen laufenden {{formcycle/}}-Server zu haben. Zur Vereinfachung der Entwicklung gibt es das //fc-server-maven-plugin//, welches mittels eines einzigen Befehls ein fertig eingerichtetes {{formcycle/}} lokal startet, wo auch bereits das Deploy-Plugin vorinstalliert ist.
@@ -289,28 +289,10 @@
  Sofern wie oben beschrieben in //~~/.m2/settings.xml// die //pluginGroup// hinterlegt wurde, kann in einem beliebiegen Verzeichnis wie folgt ein {{formcycle/}}-Server per Maven gestartet werden:
  {{code language="bash"}}
--# Aktuelle Version starten
--mvn fc-server:run-ms-war
--
--# Spezifische Version starten
--mvn de.xima.fc.maven.plugin:fc-server-maven-plugin:7.0.4:run-ms-war -DxfcVersion=7.0.16
++mvn fc-server:run-ms-war -DxfcVersion=7.0.10
  {{/code}}
--{{info}}
--Wir empfehlen die Nutzung von Java 11. Bei Nutzung von Java 17 kann es aktuell zu Problemen beim Starten von {{formcycle/}} kommen.
--{{/info}}
++Nach kurzer Wartezeit (beim ersten Mal kann es länger dauern) ist dann ein {{formcycle/}}-Server gestartet. Die URL steht am Ende in der Kommandozeile, standardmäßig http://localhost:8080/xima-formcycle
--{{info}}
--Bis einschließlich Version 7.x von {{formcycle/}} und dem Maven-Plugin ist es noch erforderlich, die package-Phase explizit aufzuführen: {{code}}mvn package fc-server:run-ms-war{{/code}}. Ab Version 8.x geschieht dies automatisch.
--{{/info}}
++Dies funktioniert auch in einem Ordner ohne Maven-Projekt. Falls keine {{formcycle/}} angegeben ist, wird eine Standard-Version genommen. Wird der Befehl innerhalb eines Plugin-Maven-Projekts ausgeführt, wird versucht, die Version von {{formcycle/}} aus dem Plugin-Projekt auszulesen.
--{{info}}
--Die Major- und Minor-Version des Maven-Plugins sollte immer der Major- und Minor-Version des zu startenden {{formcycle case="gen"/}} entsprechen. Für {{formcycle/}} 7.0.x sollte also das Maven-Plugin in Version 7.0.x verwendet werde, für {{formcycle/}} 7.1.x das Maven-Plugin in Version 7.1.x usw.
--{{/info}}
--
--Nach kurzer Wartezeit (beim ersten Mal kann es länger dauern) ist dann ein {{formcycle/}}-Server gestartet. Die URL steht am Ende in der Kommandozeile, standardmäßig http://localhost:8080/xima-formcycle Der Zugang für den Superadmin ist {{code language="plaintext"}}sadmin{{/code}} (Passwort {{code language="plaintext"}}admin{{/code}}), der Zugang für den Mandantadministrator {{code language="plaintext"}}admin{{/code}} (Passwort {{code language="plaintext"}}/admin_{{/code}}).
--
--Falls der Befehl in einem Maven-Projekt eines {{formcycle/}}-Plugins ausgeführt wird, dann wird das Plugin automatisch gebaut und nach dem Starten des Servers hochgeladen und installiert. Zudem wird versucht, die {{formcycle/}}-Version aus dem Plugin-Projekt auszulesen.
--
--Dies funktioniert auch in einem Ordner ohne Maven-Projekt. Falls keine {{formcycle/}}-Version angegeben ist, wird eine Standard-Version genommen, abhängig von der Maven-Plugin-Version.
--

pom.xml

Größe

@@ -1,1 +1,1 @@
--5.8 KB
++6.1 KB

Inhalt

@@ -15,7 +15,7 @@
  		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  		<!-- Dependencies -->
--		<xfc.version>7.2.1</xfc.version>
++		<xfc.version>7.0.10</xfc.version>
  		<junit-jupiter.version>5.6.0</junit-jupiter.version>
  		<!-- Plugins -->
@@ -23,10 +23,18 @@
  		<maven-compiler-plugin.version>3.8.1</maven-compiler-plugin.version>
  		<maven-jar-plugin.version>3.1.0</maven-jar-plugin.version>
  		<maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
--		<fc-deploy-plugin-maven-plugin.version>7.0.1</fc-deploy-plugin-maven-plugin.version>
++		<fc-deploy-plugin-maven-plugin.version>7.0.1<fc-deploy-plugin-maven-plugin.version/>
  		<fc-server-maven-plugin.version>7.0.1</fc-server-maven-plugin.version>
  	</properties>
++	<repositories>
++		<repository>
++			<id>xima</id>
++			<name>fc-plugin-dev</name>
++			<url>http://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
++		</repository>
++	</repositories>
++
  	<dependencies>
  		<!-- Reference FORMCYCLE libraries. The plugin is installed in a running -->
  		<!-- FORMCYCLE system, , so you do not need to include the FORMCYCLE libraries -->
@@ -58,11 +58,20 @@
  		<plugins>
  			<!-- Upload the plugin to a running FORMCYCLE server as part of the Maven build process -->
--			<!-- mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin -->
++			<!-- mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin -->
  			<plugin>
  				<groupId>de.xima.fc.maven.plugin</groupId>
  				<artifactId>fc-deploy-plugin-maven-plugin</artifactId>
  				<version>${fc-deploy-plugin-maven-plugin.version}</version>
++				<executions>
++					<execution>
++						<id>upload</id>
++						<phase>install</phase>
++						<goals>
++							<goal>deploy</goal>
++						</goals>
++					</execution>
++				</executions>
  			</plugin>
  			<!-- Start a preconfigured FORMCYCLE server-->
@@ -139,7 +139,6 @@
  								<manifestEntries>
  									<formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
  									<Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
--									<Plugin-Key>${project.groupId}:${project.artifactId}</Plugin-Key>
  									<Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
  									<Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
  									<Implementation-Version>${project.version}</Implementation-Version>