Änderungen von Dokument Plugin-Entwicklung

Von Version 3.13
bearbeitet von awa
am 25.02.2022, 12:19
Änderungskommentar: Es gibt keinen Kommentar für diese Version
Auf Version 2.1
bearbeitet von rth
am 14.02.2022, 17:25
Änderungskommentar: Neuen Anhang pom.xml hochladen

Zusammenfassung

Details

Seiteneigenschaften
Dokument-Autor
... ... @@ -1,1 +1,1 @@
1 -XWiki.awa
1 +XWiki.rth
Inhalt
... ... @@ -8,96 +8,86 @@
8 8  
9 9  Die API-Dokumentation für {{formcycle/}} findet sich hier auf unserer Seite: [[Javadocs>>https://docs.formcycle.eu/]]
10 10  
11 -== Maven-Setup ==
11 +== Projekt-Setup ==
12 12  
13 -Zu Beginn der Entwicklung eines Plugins ist es nötig das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
13 +Zu Beginn der Entwicklung eines Plugins ist es nötig das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren. Für letzteres kommt hierbei das Build-Management-Tool [[Apache Maven>>url:https://maven.apache.org/||rel="__blank"]] zum Einsatz. Um die entsprechenden Abhängigkeiten zu {{formcycle case="dat"/}} bereitzustellen ist ein 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 beinhaltet alle öffentlich zur Verfügung stehenden Artefakte welche dem Plugin zur Laufzeit bereitgestellt und während der Entwicklung benötigt werden. Augangspunkt ist hierbei das Artefakt //fc-plugin-common//, welches die einzelnen Plugin-Schnittstellen beinhaltet und auch auf [[unserere Downloadseite zur Verfügung steht>>url:http://artifactory.xima-services.de/artifactory/fc-plugin-dev/de/xima/fc/fc-plugin-common/]]. Ein Auszug des Project Object Models (pom.xml) sieht dem entsprechend beispielhaft wie folgt aus:
14 14  
15 -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.
16 -
17 -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.
18 -
19 -Damit das Repository auch beim Bauen mit Maven verwendet wird, sollte folgendes in die Maven-Konfigurationsdatei //settings.xml// geschrieben werden. Diese Datei findet sich in der Regeln im //.m2//-Ordner im Home-Verzeichnis des aktuellen Nutzers. Unter Linux //~/.m2/settings.xml// und unter Windows //%homepath%\.m2\settings.xml//:
20 -
21 -{{panel title="~~~~/.m2/settings.xml" fullwidth="true" initial="hidden" triggerable="true"}}
15 +{{panel title="Beispiel für pom.xml" fullwidth="true" initial="hidden" triggerable="true"}}
22 22  {{code language="xml"}}
23 -<?xml version="1.0" encoding="UTF-8"?>
24 -<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.1.0"
25 - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
17 +<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
18 + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
26 26  
27 - <!-- Add XIMA artifactory -->
28 - <profiles>
29 - <profile>
30 - <!-- FORMCYCLE dependencies -->
31 - <repositories>
32 - <repository>
33 - <snapshots>
34 - <enabled>false</enabled>
35 - </snapshots>
36 - <id>xima</id>
37 - <name>libs-release</name>
38 - <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
39 - </repository>
40 - </repositories>
41 - <!-- Maven plugins for FORMCYCLE -->
42 - <pluginRepositories>
43 - <pluginRepository>
44 - <snapshots>
45 - <enabled>false</enabled>
46 - </snapshots>
47 - <id>xima</id>
48 - <name>plugins-release</name>
49 - <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
50 - </pluginRepository>
51 - </pluginRepositories>
52 - <id>xima-artifactory</id>
53 - </profile>
54 - </profiles>
20 +...
55 55  
56 - <!-- Enable XIMA artifactory by default -->
57 - <activeProfiles>
58 - <activeProfile>xima-artifactory</activeProfile>
59 - </activeProfiles>
22 + <properties>
23 + <!-- Configuration -->
24 + <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
60 60  
61 - <!-- FORMCYCLE specific Maven plugins provided by XIMA -->
62 - <pluginGroups>
63 - <pluginGroup>de.xima.fc.maven.plugin</pluginGroup>
64 - </pluginGroups>
65 -</settings>
66 -{{/code}}
67 -{{/panel}}
26 + <!-- Dependencies -->
27 + <xfc.version>7.0.9</xfc.version>
68 68  
69 -== Maven-Projekteinrichtung
29 + <!-- Plugins -->
30 + <maven-compiler-plugin.version>3.8.1</maven-compiler-plugin.version>
31 + <maven-jar-plugin.version>3.1.0</maven-jar-plugin.version>
32 + </properties>
70 70  
71 -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"]].
34 + <repositories>
35 + <repository>
36 + <id>xima</id>
37 + <name>fc-plugin-dev</name>
38 + <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
39 + </repository>
40 + </repositories>
72 72  
73 -=== Artekfakte und Abhängigkeiten
42 + <dependencies>
43 + <dependency>
44 + <groupId>de.xima.fc</groupId>
45 + <artifactId>fc-plugin-common</artifactId>
46 + <version>${xfc.version}</version>
47 + <scope>provided</scope>
48 + </dependency>
49 + </dependencies>
74 74  
75 -{{info}}
76 -Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
77 -{{/info}}
51 + <build>
52 + <plugins>
53 + <plugin>
54 + <groupId>org.apache.maven.plugins</groupId>
55 + <artifactId>maven-compiler-plugin</artifactId>
56 + <version>${maven-compiler-plugin.version}</version>
57 + <configuration>
58 + <release>11</release>
59 + <encoding>UTF-8</encoding>
60 + </configuration>
61 + </plugin>
78 78  
79 -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/]].
63 + <plugin>
64 + <groupId>org.apache.maven.plugins</groupId>
65 + <artifactId>maven-jar-plugin</artifactId>
66 + <version>${maven-jar-plugin.version}</version>
67 + <configuration>
68 + <archive>
69 + <manifest>
70 + <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
71 + </manifest>
72 + <manifestEntries>
73 + <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
74 + <Build-Time>${maven.build.timestamp}</Build-Time>
75 + </manifestEntries>
76 + </archive>
77 + </configuration>
78 + </plugin>
80 80  
81 -In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:
80 + </plugins>
81 + </build>
82 +</project>
82 82  
83 -{{code language="xml"}}
84 - <properties>
85 - <xfc.version>7.0.10</xfc.version>
86 - </properties>
87 -
88 - <dependencies>
89 - <dependency>
90 - <groupId>de.xima.fc</groupId>
91 - <artifactId>fc-plugin-common</artifactId>
92 - <version>${xfc.version}</version>
93 - <scope>provided</scope>
94 - </dependency>
95 - </dependencies>
96 96  {{/code}}
85 +{{/panel}}
97 97  
98 98  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:
99 99  
100 100  {{code language="xml"}}
90 +...
101 101   <dependency>
102 102   <groupId>de.xima.fc</groupId>
103 103   <artifactId>fc-logic</artifactId>
... ... @@ -104,6 +104,7 @@
104 104   <version>${xfc.version}</version>
105 105   <scope>provided</scope>
106 106   </dependency>
97 +...
107 107  {{/code}}
108 108  
109 109  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"]].
... ... @@ -110,99 +110,12 @@
110 110  
111 111  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).
112 112  
113 -=== Manifest und Fat JAR
104 +{{info}}
105 +Alle Abhangigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
106 +{{/info}}
114 114  
115 -In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
108 +Basierend auf der hiermit zur Verfügung stehenden Infrastruktur steht der Entwicklung von eigenen Plugin-Implementierungen nichts mehr im Wege. Die Installation erfolgt anschließend je nach Verwendungszweck über die Oberflächen [[Mandant-Plugins>>doc:Formcycle.UserInterface.Client.Plugins]] oder [[System-Plugins>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins]].
116 116  
117 -; formcycle-version-requirement
118 -: Erforderlich. Version von {{formcycle/}}, für die das Plugin gedacht ist.Ist erforderlich, damit {{formcycle/}} bei der Installation die Kompatibilität prüfen kann.
119 -; Implementation-Version
120 -: Erforderlich. Version des Plugins, wird etwa in der Oberfläche angezeigt.
121 -; Build-Time oder Build-Timestamp
122 -: Optional, wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren.
123 -; Implementation-Title
124 -: Optional, wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren.
110 +== Demo-Plugins ==
125 125  
126 -Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden.
127 -
128 -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).
129 -
130 -Dies kann entweder über das [[maven-assembly-plugin>>url:https://maven.apache.org/plugins/maven-assembly-plugin/]] oder das [[maven-shade-plugin>>url:https://maven.apache.org/plugins/maven-shade-plugin/]] erfolgen. Letzteres ist für forgeschrittene Anwendungsfälle gedacht, wenn etwa mehrere Abhängigkeiten die gleichen Dateien mitbringen und zusammengeführt werden müssen.
131 -
132 -Für einfache Plugins ist das //maven-assembly-plugin// ausreichend. Dieses kann in der //pom.xml// wie folgt konfiguriert werden:
133 -
134 -{{panel title="maven-assembly-plugin in pom.xml" fullwidth="true" initial="hidden" triggerable="true"}}
135 -{{code language="java"}}
136 - <properties>
137 - <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
138 - </properties>
139 - <build>
140 - <finalName>${project.parent.artifactId}</finalName>
141 - <plugins>
142 - <plugin>
143 - <groupId>org.apache.maven.plugins</groupId>
144 - <artifactId>maven-assembly-plugin</artifactId>
145 - <version>${maven-assembly-plugin.version}</version>
146 - <executions>
147 - <execution>
148 - <id>fat-jar</id>
149 - <phase>package</phase>
150 - <goals>
151 - <goal>single</goal>
152 - </goals>
153 - <configuration>
154 - <finalName>${project.parent.artifactId}</finalName>
155 - <appendAssemblyId>false</appendAssemblyId>
156 - <descriptorRefs>
157 - <descriptorRef>jar-with-dependencies</descriptorRef>
158 - </descriptorRefs>
159 - <archive>
160 - <manifest>
161 - <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
162 - </manifest>
163 - <manifestEntries>
164 - <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
165 - <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
166 - <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
167 - <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
168 - <Implementation-Version>${project.version}</Implementation-Version>
169 - </manifestEntries>
170 - </archive>
171 - </configuration>
172 - </execution>
173 - </executions>
174 - </plugin>
175 - </plugins>
176 - </build>
177 -{{/code}}
178 -{{/panel}}
179 -
180 -=== Bauen und Installieren ===
181 -
182 -Der genaue Befehl zum Bauen hängt von den konkreten Einstellungen in der //pom.xml// ab. In der Regel sollte aber folgender Standardbefehl im Plugin-Verzeichnis funktionieren:
183 -
184 -{{code}}
185 - mvn clean install
186 -{{/code}}
187 -
188 -Nachdem das Plugin erfolgreich gebaut wurde, kann die so entstandene JAR-Datei in {{formcycle/}} über die Oberfläche [[Mandant-Plugins>>doc:Formcycle.UserInterface.Client.Plugins]] beziehungsweise [[System-Plugins>>doc:Formcycle.SystemSettings.UserInterface.SystemPlugins]] hochgeladen werden.
189 -
190 -Zum automatischen Hochladen gibt es zudem das Deploy-Plugin, siehe unten.
191 -
192 -Zum Starten eines einfachen {{formcycle/}}-Servers gibt es das FC-Server-Plugin, siehe ebenfalls unten.
193 -
194 -== Maven-Archetypes ==
195 -
196 -TODO
197 -
198 -Um einen besseren Einstieg in die Plugin-Entwicklung zu finden, [[bieten wir auf unserer Downloadseite>>url:https://customer.formcycle.eu/index.php/s/PgdMrNOvbYEzhmr]]
199 -
200 -== Deploy-Plugin
201 -
202 -TODO
203 -
204 -== FC-Server-Plugin
205 -
206 -TODO
207 -
208 -
112 +Um einen besseren Einstieg in die Plugin-Entwicklung zu finden, [[bieten wir auf unserer Downloadseite>>url:https://customer.formcycle.eu/index.php/s/PgdMrNOvbYEzhmr]] auch für jeden Plugintyp ein kommentiertes Demo-Maven-Projekt an. Sie können diese herunterladen und in der Entwicklungsumgebung ihrer Wahl einsehen und kompilieren.