Änderungen von Dokument Plugin-Entwicklung

Von Version 5.8
bearbeitet von awa
am 25.02.2022, 13:25
Änderungskommentar: Es gibt keinen Kommentar für diese Version
Auf Version 10.1
bearbeitet von awa
am 25.02.2022, 22:48
Änderungskommentar: Neuen Anhang pom.xml hochladen

Zusammenfassung

Details

Seiteneigenschaften
Inhalt
... ... @@ -9,9 +9,9 @@
9 9  
10 10  == Maven-Setup ==
11 11  
12 -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.
13 13  
14 -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.
15 15  
16 16  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.
17 17  
... ... @@ -33,7 +33,7 @@
33 33   <enabled>false</enabled>
34 34   </snapshots>
35 35   <id>xima</id>
36 - <name>libs-release</name>
36 + <name>fc-plugin-dev</name>
37 37   <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
38 38   </repository>
39 39   </repositories>
... ... @@ -44,7 +44,7 @@
44 44   <enabled>false</enabled>
45 45   </snapshots>
46 46   <id>xima</id>
47 - <name>plugins-release</name>
47 + <name>fc-plugin-dev</name>
48 48   <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
49 49   </pluginRepository>
50 50   </pluginRepositories>
... ... @@ -65,18 +65,20 @@
65 65  {{/code}}
66 66  {{/panel}}
67 67  
68 -== Maven-Projekteinrichtung
68 +== Maven-Projekteinrichtung ===
69 69  
70 70  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"]].
71 71  
72 -=== Artekfakte und Abhängigkeiten
72 +=== Artekfakte und Abhängigkeiten ===
73 73  
74 74  {{info}}
75 75  Alle Abhängigkeiten zu {{formcycle case="dat"/}} sind im scope "provided" zu definieren!
76 76  {{/info}}
77 77  
78 -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"]].
79 79  
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 +
80 80  In der //pom.xml// des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:
81 81  
82 82  {{code language="xml"}}
... ... @@ -94,7 +94,7 @@
94 94   </dependencies>
95 95  {{/code}}
96 96  
97 -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:
98 98  
99 99  {{code language="xml"}}
100 100   <dependency>
... ... @@ -105,22 +105,22 @@
105 105   </dependency>
106 106  {{/code}}
107 107  
108 -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.
109 109  
110 110  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).
111 111  
112 -=== Manifest und Fat JAR
114 +=== Manifest und Fat JAR ===
113 113  
114 114  In der //META-INF/MANIFEST.MF// in der Plugin-JAR-Datei sollten folgende Informationen stehen:
115 115  
116 116  ; formcycle-version-requirement
117 -: 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.
118 118  ; Implementation-Version
119 -: 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.
120 120  ; Build-Time oder Build-Timestamp
121 -: 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.
122 122  ; Implementation-Title
123 -: 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.
124 124  
125 125  Diese Informationen können wie unten beschrieben mittels des //maven-assembly-plugin// in die Manifest-Datei geschrieben werden.
126 126  
... ... @@ -136,7 +136,7 @@
136 136   <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
137 137   </properties>
138 138   <build>
139 - <finalName>${project.parent.artifactId}</finalName>
141 + <finalName>${project.artifactId}</finalName>
140 140   <plugins>
141 141   <plugin>
142 142   <groupId>org.apache.maven.plugins</groupId>
... ... @@ -150,7 +150,7 @@
150 150   <goal>single</goal>
151 151   </goals>
152 152   <configuration>
153 - <finalName>${project.parent.artifactId}</finalName>
155 + <finalName>${project.artifactId}</finalName>
154 154   <appendAssemblyId>false</appendAssemblyId>
155 155   <descriptorRefs>
156 156   <descriptorRef>jar-with-dependencies</descriptorRef>
... ... @@ -216,7 +216,7 @@
216 216  
217 217  {{code language="plaintext"}}https://artifactory.xima-services.de/artifactory/libs-release-local/archetype-catalog.xml{{/code}}
218 218  
219 -== Deploy-Plugin
221 +== Deploy-Plugin ==
220 220  
221 221  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:
222 222  
... ... @@ -237,7 +237,7 @@
237 237   <executions>
238 238   <execution>
239 239   <id>upload</id>
240 - <phase>install</phase>
242 + <phase>package</phase>
241 241   <goals>
242 242   <goal>deploy</goal>
243 243   </goals>
... ... @@ -251,7 +251,7 @@
251 251  Sofern das Deploy-Plugin bereits in {{formcycle/}} installiert ist, kann das Plugin-Projekt dann beim Bauen wie folgt hochgeladen werden:
252 252  
253 253  {{code language="bash"}}
254 -mvn clean install -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
256 +mvn package -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin
255 255  {{/code}}
256 256  
257 257  Wird Eclipse benutzt, kann auch eine Launch-Configuration mit den //fcDeployUrl// und dem //fcDeployToken// angelegt werden.
... ... @@ -263,10 +263,10 @@
263 263  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:
264 264  
265 265  {{code language="bash"}}
266 -mvn fc-server:run-ms-war -DxfcVersion=7.0.10
268 +mvn package fc-server:run-ms-war -DxfcVersion=7.0.10
267 267  {{/code}}
268 268  
269 -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 +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}}).
270 270  
271 271  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.
272 272  
pom.xml
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.rth
1 +XWiki.awa
Größe
... ... @@ -1,1 +1,1 @@
1 -2.2 KB
1 +5.7 KB
Inhalt
... ... @@ -2,55 +2,89 @@
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 - <repositories>
25 - <repository>
26 - <id>xima</id>
27 - <name>fc-plugin-dev</name>
28 - <url>http://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
29 - </repository>
30 - </repositories>
31 -
32 32   <dependencies>
31 + <!-- Reference FORMCYCLE libraries. The plugin is installed in a running -->
32 + <!-- FORMCYCLE system, , so you do not need to include the FORMCYCLE libraries -->
33 + <!-- 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>
36 + <artifactId>fc-logic</artifactId>
37 + <version>${xfc.version}</version>
37 37   <scope>provided</scope>
38 38   </dependency>
39 39  
41 + <!-- 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>
43 + <groupId>org.junit.jupiter</groupId>
44 + <artifactId>junit-jupiter</artifactId>
45 + <version>${junit-jupiter.version}</version>
46 + <scope>test</scope>
45 45   </dependency>
48 +
49 + <!-- You can add additional dependencies here. -->
50 + <!-- Some common libraries as apache-commons and guava are provided by -->
51 + <!-- FORMCYCLE and can be set to scope=provided. -->
52 +
46 46   </dependencies>
47 47  
48 48   <build>
56 + <finalName>${project.artifactId}</finalName>
57 +
49 49   <plugins>
59 +
60 + <!-- Upload the plugin to a running FORMCYCLE server as part of the Maven build process -->
61 + <!-- mvn package fc-deploy:deploy -DfcDeployUrl=http://localhost:8080/xima-formcycle -DfcDeployToken=admin -->
50 50   <plugin>
63 + <groupId>de.xima.fc.maven.plugin</groupId>
64 + <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
65 + <version>${fc-deploy-plugin-maven-plugin.version}</version>
66 + </plugin>
67 +
68 + <!-- Start a preconfigured FORMCYCLE server-->
69 + <!-- mvn fc-server:run-ms-war -->
70 + <plugin>
71 + <groupId>de.xima.fc.maven.plugin</groupId>
72 + <artifactId>fc-server-maven-plugin</artifactId>
73 + <version>${fc-server-maven-plugin.version}</version>
74 + <configuration>
75 + <bootstrap>
76 + <pluginManagement>
77 + <deployMavenProject>true</deployMavenProject>
78 + </pluginManagement>
79 + </bootstrap>
80 + </configuration>
81 + </plugin>
82 +
83 + <!-- Configure the compilation process. At least Java 11 is required. -->
84 + <plugin>
51 51   <groupId>org.apache.maven.plugins</groupId>
52 52   <artifactId>maven-compiler-plugin</artifactId>
53 - <version>${maven-compiler-plugin-version}</version>
87 + <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  
96 + <!-- 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>
100 + <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>
107 + <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
108 + <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
109 + <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
110 + <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
111 + <Implementation-Version>${project.version}</Implementation-Version>
73 73   </manifestEntries>
74 74   </archive>
75 75   </configuration>
76 76   </plugin>
116 +
117 + <!-- Build a fat JAR with all dependencies included -->
118 + <plugin>
119 + <groupId>org.apache.maven.plugins</groupId>
120 + <artifactId>maven-assembly-plugin</artifactId>
121 + <version>${maven-assembly-plugin.version}</version>
122 + <executions>
123 + <execution>
124 + <id>fat-jar</id>
125 + <phase>package</phase>
126 + <goals>
127 + <goal>single</goal>
128 + </goals>
129 + <configuration>
130 + <finalName>${project.artifactId}</finalName>
131 + <appendAssemblyId>false</appendAssemblyId>
132 + <descriptorRefs>
133 + <descriptorRef>jar-with-dependencies</descriptorRef>
134 + </descriptorRefs>
135 + <archive>
136 + <manifest>
137 + <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
138 + </manifest>
139 + <manifestEntries>
140 + <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
141 + <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
142 + <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
143 + <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
144 + <Implementation-Version>${project.version}</Implementation-Version>
145 + </manifestEntries>
146 + </archive>
147 + </configuration>
148 + </execution>
149 + </executions>
150 + </plugin>
151 +
152 + <!-- Use JUnit to run test classes -->
153 + <plugin>
154 + <groupId>org.apache.maven.plugins</groupId>
155 + <artifactId>maven-surefire-plugin</artifactId>
156 + <version>${maven-surefire-plugin.version}</version>
157 + </plugin>
77 77   </plugins>
78 78   </build>
79 79  </project>
161 +