Änderungen von Dokument Plugin-Entwicklung

Von Version 5.6
bearbeitet von awa
am 25.02.2022, 13:22
Änderungskommentar: Es gibt keinen Kommentar für diese Version
Auf Version 7.2
bearbeitet von gru
am 25.02.2022, 15:23
Änderungskommentar: Es gibt keinen Kommentar für diese Version

Zusammenfassung

Details

Seiteneigenschaften
Dokument-Autor
... ... @@ -1,1 +1,1 @@
1 -XWiki.awa
1 +XWiki.gru
Inhalt
... ... @@ -1,6 +1,5 @@
1 1  {{content/}}
2 2  
3 -== Plugins für zusätzliche Funktionalitäten ==
4 4  
5 5  {{formcycle/}} bietet ein Vielzahl von Einstiegspunkten für die Erweiterung der Standard-Funktionalitäten durch Plugins. Basierend auf den einzelnen [[Plugin-Typen>>doc:Formcycle.PluginDevelopment.Types.WebHome]] werden diese zu gewissen Zeitpunkten automatisch oder manuell angesprochen und erlauben es somit von der Ersetzung eigener Platzhalter bis hin zur Implementierung eigener Verarbeitungslogik {{formcycle/}} anzupassen. Als fundamentaler erster Schritt für die Entwicklung eigener Plugins ist hierbei das Erstellen eines entsprechenden Java-Projekts anzusehen.
6 6  
... ... @@ -10,9 +10,9 @@
10 10  
11 11  == Maven-Setup ==
12 12  
13 -Zu Beginn der Entwicklung eines Plugins ist es nötig das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
12 +Zu Beginn der Entwicklung eines Plugins ist es nötig, das entsprechende Entwicklungsprojekt aufzusetzten und zu konfigurieren.
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.
14 +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.
16 16  
17 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 18  
... ... @@ -34,7 +34,7 @@
34 34   <enabled>false</enabled>
35 35   </snapshots>
36 36   <id>xima</id>
37 - <name>libs-release</name>
36 + <name>fc-plugin-dev</name>
38 38   <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
39 39   </repository>
40 40   </repositories>
... ... @@ -45,7 +45,7 @@
45 45   <enabled>false</enabled>
46 46   </snapshots>
47 47   <id>xima</id>
48 - <name>plugins-release</name>
47 + <name>fc-plugin-dev</name>
49 49   <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
50 50   </pluginRepository>
51 51   </pluginRepositories>
... ... @@ -66,18 +66,20 @@
66 66  {{/code}}
67 67  {{/panel}}
68 68  
69 -== Maven-Projekteinrichtung
68 +== Maven-Projekteinrichtung ===
70 70  
71 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"]].
72 72  
73 -=== Artekfakte und Abhängigkeiten
72 +=== Artekfakte und Abhängigkeiten ===
74 74  
75 75  {{info}}
76 76  Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
77 77  {{/info}}
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||target="_blank"]].
78 +Eine fertige einfache //pom.xml// können Sie [[hier herunterladen>>attach:pom.xml||rel="__blank"]].
80 80  
80 +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||target="_blank"]].
81 +
81 81  In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:
82 82  
83 83  {{code language="xml"}}
... ... @@ -95,7 +95,7 @@
95 95   </dependencies>
96 96  {{/code}}
97 97  
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 +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:
99 99  
100 100  {{code language="xml"}}
101 101   <dependency>
... ... @@ -106,22 +106,22 @@
106 106   </dependency>
107 107  {{/code}}
108 108  
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 +Eine entsprechende Benutzung ist vor allem bei der Verwendung der Datenbankschnittstelle sowie bei der Implementierung von eigenen Verarbeitungen nötig.
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
114 +=== Manifest und Fat JAR ===
114 114  
115 115  In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
116 116  
117 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 +: 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 119  ; Implementation-Version
120 -: Erforderlich. Version des Plugins, wird etwa in der Oberfläche angezeigt.
121 +: Erforderlich. Version des Plugins; Diese wird z.B. in der Oberfläche angezeigt.
121 121  ; Build-Time oder Build-Timestamp
122 -: Optional, wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren.
123 +: Optional. Wird bei SNAPSHOT-Versionen mit angezeigt, um den SNAPSHOT zu identifizieren.
123 123  ; Implementation-Title
124 -: Optional, wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren.
125 +: Optional. Wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren.
125 125  
126 126  Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden.
127 127  
... ... @@ -137,7 +137,7 @@
137 137   <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
138 138   </properties>
139 139   <build>
140 - <finalName>${project.parent.artifactId}</finalName>
141 + <finalName>${project.artifactId}</finalName>
141 141   <plugins>
142 142   <plugin>
143 143   <groupId>org.apache.maven.plugins</groupId>
... ... @@ -151,7 +151,7 @@
151 151   <goal>single</goal>
152 152   </goals>
153 153   <configuration>
154 - <finalName>${project.parent.artifactId}</finalName>
155 + <finalName>${project.artifactId}</finalName>
155 155   <appendAssemblyId>false</appendAssemblyId>
156 156   <descriptorRefs>
157 157   <descriptorRef>jar-with-dependencies</descriptorRef>
... ... @@ -217,7 +217,7 @@
217 217  
218 218  {{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}}
219 219  
220 -== Deploy-Plugin
221 +== Deploy-Plugin ==
221 221  
222 222  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:
223 223  
... ... @@ -267,5 +267,7 @@
267 267  mvn fc-server:run-ms-war -DxfcVersion=7.0.10
268 268  {{/code}}
269 269  
270 -Dies funktioniert auch in einem Ordner ohne Maven-Projekt. Falls keine {{formcycle/}} angegeben ist, wird eine Standard-Version genommen.
271 +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
271 271  
273 +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.
274 +
pom.xml
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.rth
1 +XWiki.awa
Größe
... ... @@ -1,1 +1,1 @@
1 -2.2 KB
1 +6.1 KB
Inhalt
... ... @@ -2,23 +2,29 @@
2 2   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
3 3   <modelVersion>4.0.0</modelVersion>
4 4  
5 + <!-- MUST BE FILLED IN -->
5 5   <groupId></groupId>
6 6   <artifactId></artifactId>
7 7   <version></version>
8 - <packaging>jar</packaging>
9 -
10 10   <name></name>
11 11  
11 + <packaging>jar</packaging>
12 +
12 12   <properties>
13 13   <!-- Configuration -->
14 14   <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
15 15  
16 16   <!-- Dependencies -->
17 - <xfc-version>7.0.9</xfc-version>
18 + <xfc.version>7.0.10</xfc.version>
19 + <junit-jupiter.version>5.6.0</junit-jupiter.version>
18 18  
19 19   <!-- Plugins -->
20 - <maven-compiler-plugin-version>3.8.1</maven-compiler-plugin-version>
21 - <maven-jar-plugin-version>3.1.0</maven-jar-plugin-version>
22 + <maven-surefire-plugin.version>2.22.2</maven-surefire-plugin.version>
23 + <maven-compiler-plugin.version>3.8.1</maven-compiler-plugin.version>
24 + <maven-jar-plugin.version>3.1.0</maven-jar-plugin.version>
25 + <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
26 + <fc-deploy-plugin-maven-plugin.version>7.0.1</fc-deploy-plugin-maven-plugin.version>
27 + <fc-server-maven-plugin.version>7.0.1</fc-server-maven-plugin.version>
22 22   </properties>
23 23  
24 24   <repositories>
... ... @@ -30,27 +30,72 @@
30 30   </repositories>
31 31  
32 32   <dependencies>
39 + <!-- Reference FORMCYCLE libraries. The plugin is installed in a running -->
40 + <!-- FORMCYCLE system, , so you do not need to include the FORMCYCLE libraries -->
41 + <!-- in the plugin JAR. This is done by setting the scope to "provided" -->
33 33   <dependency>
34 34   <groupId>de.xima.fc</groupId>
35 - <artifactId>fc-plugin-common</artifactId>
36 - <version>${xfc-version}</version>
44 + <artifactId>fc-logic</artifactId>
45 + <version>${xfc.version}</version>
37 37   <scope>provided</scope>
38 38   </dependency>
39 39  
49 + <!-- JUnit for writing unit tests -->
40 40   <dependency>
41 - <groupId>de.xima.fc</groupId>
42 - <artifactId>fc-logic</artifactId>
43 - <version>${xfc-version}</version>
44 - <scope>provided</scope>
51 + <groupId>org.junit.jupiter</groupId>
52 + <artifactId>junit-jupiter</artifactId>
53 + <version>${junit-jupiter.version}</version>
54 + <scope>test</scope>
45 45   </dependency>
56 +
57 + <!-- You can add additional dependencies here. -->
58 + <!-- Some common libraries as apache-commons and guava are provided by -->
59 + <!-- FORMCYCLE and can be set to scope=provided. -->
60 +
46 46   </dependencies>
47 47  
48 48   <build>
64 + <finalName>${project.artifactId}</finalName>
65 +
49 49   <plugins>
67 +
68 + <!-- Upload the plugin to a running FORMCYCLE server as part of the Maven build process -->
69 + <!-- mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin -->
50 50   <plugin>
71 + <groupId>de.xima.fc.maven.plugin</groupId>
72 + <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
73 + <version>${fc-deploy-plugin-maven-plugin.version}</version>
74 + <executions>
75 + <execution>
76 + <id>upload</id>
77 + <phase>install</phase>
78 + <goals>
79 + <goal>deploy</goal>
80 + </goals>
81 + </execution>
82 + </executions>
83 + </plugin>
84 +
85 + <!-- Start a preconfigured FORMCYCLE server-->
86 + <!-- mvn fc-server:run-ms-war -->
87 + <plugin>
88 + <groupId>de.xima.fc.maven.plugin</groupId>
89 + <artifactId>fc-server-maven-plugin</artifactId>
90 + <version>${fc-server-maven-plugin.version}</version>
91 + <configuration>
92 + <bootstrap>
93 + <pluginManagement>
94 + <deployMavenProject>true</deployMavenProject>
95 + </pluginManagement>
96 + </bootstrap>
97 + </configuration>
98 + </plugin>
99 +
100 + <!-- Configure the compilation process. At least Java 11 is required. -->
101 + <plugin>
51 51   <groupId>org.apache.maven.plugins</groupId>
52 52   <artifactId>maven-compiler-plugin</artifactId>
53 - <version>${maven-compiler-plugin-version}</version>
104 + <version>${maven-compiler-plugin.version}</version>
54 54   <configuration>
55 55   <release>11</release>
56 56   <encoding>UTF-8</encoding>
... ... @@ -59,10 +59,11 @@
59 59   </configuration>
60 60   </plugin>
61 61  
113 + <!-- Configure how the JAR is created, including manifest entries -->
62 62   <plugin>
63 63   <groupId>org.apache.maven.plugins</groupId>
64 64   <artifactId>maven-jar-plugin</artifactId>
65 - <version>${maven-jar-plugin-version}</version>
117 + <version>${maven-jar-plugin.version}</version>
66 66   <configuration>
67 67   <archive>
68 68   <manifest>
... ... @@ -69,11 +69,58 @@
69 69   <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
70 70   </manifest>
71 71   <manifestEntries>
72 - <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
124 + <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
125 + <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
126 + <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
127 + <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
128 + <Implementation-Version>${project.version}</Implementation-Version>
73 73   </manifestEntries>
74 74   </archive>
75 75   </configuration>
76 76   </plugin>
133 +
134 + <!-- Build a fat JAR with all dependencies included -->
135 + <plugin>
136 + <groupId>org.apache.maven.plugins</groupId>
137 + <artifactId>maven-assembly-plugin</artifactId>
138 + <version>${maven-assembly-plugin.version}</version>
139 + <executions>
140 + <execution>
141 + <id>fat-jar</id>
142 + <phase>package</phase>
143 + <goals>
144 + <goal>single</goal>
145 + </goals>
146 + <configuration>
147 + <finalName>${project.artifactId}</finalName>
148 + <appendAssemblyId>false</appendAssemblyId>
149 + <descriptorRefs>
150 + <descriptorRef>jar-with-dependencies</descriptorRef>
151 + </descriptorRefs>
152 + <archive>
153 + <manifest>
154 + <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
155 + </manifest>
156 + <manifestEntries>
157 + <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
158 + <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
159 + <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
160 + <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
161 + <Implementation-Version>${project.version}</Implementation-Version>
162 + </manifestEntries>
163 + </archive>
164 + </configuration>
165 + </execution>
166 + </executions>
167 + </plugin>
168 +
169 + <!-- Use JUnit to run test classes -->
170 + <plugin>
171 + <groupId>org.apache.maven.plugins</groupId>
172 + <artifactId>maven-surefire-plugin</artifactId>
173 + <version>${maven-surefire-plugin.version}</version>
174 + </plugin>
77 77   </plugins>
78 78   </build>
79 79  </project>
178 +