Änderungen von Dokument FORMCYCLE-Deploy-Plugin-Plugin

Von Version < 1.24 >
bearbeitet von awa
am 12.03.2020, 13:45
Auf Version < 1.29 >
bearbeitet von awa
am 12.03.2020, 15:31
< >
Änderungskommentar: Es gibt keinen Kommentar für diese Version

Zusammenfassung

Details

Seiteneigenschaften
Inhalt
... ... @@ -1,11 +1,13 @@
1 +Hinweis zum Namen: Es ist ein Plugin zum Deployen von Plugins in {{formcycle/}}, daher //FORMCYCLE-Deploy-Plugin-Plugin//.
2 +
1 1  {{content/}}
2 2  
3 -Mit dem Deploy-Plugin können Plugins automatisch in die FORMCYCLE-Anwendung hochgeladen und dort installiert werden. Dies hat gegenüber der manuellen Installation über das entsprechende [[Menü im Backend>>doc:Formcycle.UserInterface.Client.Plugins]] einige Vorteile:
5 +Mit dem Deploy-Plugin können Plugins automatisch in die {{formcycle/}}-Anwendung hochgeladen und dort installiert werden. Dies hat gegenüber der manuellen Installation über das entsprechende [[Menü im Backend>>doc:Formcycle.UserInterface.Client.Plugins]] einige Vorteile:
4 4  
5 5  * Plugin-Entwickler können beim Maven-Build das Plugin automatisch am Ende des Builds hochladen. So kann der Entwickler schneller testen.
6 6  * Eine Installation auf einem Live-System kann so weiter automatisiert werden.
7 7  
8 -Das Deploy-Plugin kann sowohl als Mandant-Plugin als auch als System-Plugin installiert werden. Es enthält eine [[Servlet-Aktion>>doc:Formcycle.PluginDevelopment.Types.IPluginServletAction]]. Per HTTP-Post-Request wird eine Plugin-JAR-Datei an den FORMCYCLE-Server gesendet. Die weiteren Parameter im HTTP-Request bestimmen, was nun weiter mit dem Plugin geschieht, etwa ob es nur installiert oder auch aktiviert werden soll.
10 +Das Deploy-Plugin kann sowohl als Mandant-Plugin als auch als System-Plugin installiert werden. Es enthält eine [[Servlet-Aktion>>doc:Formcycle.PluginDevelopment.Types.IPluginServletAction]]. Per HTTP-Post-Request wird eine Plugin-JAR-Datei an den {{formcycle/}}-Server gesendet. Die weiteren Parameter im HTTP-Request bestimmen, was nun weiter mit dem Plugin geschieht, etwa ob es nur installiert oder auch aktiviert werden soll.
9 9  
10 10  Falls das hochgeladene Plugin bereits existiert, ist es in der Regel ist es sinnvoll, dieses zu ersetzen. Dazu ist es erforderlich, anzugeben, über welchen Identifikator ein Plugin identifiziert wird. Es gibt hierbei vier Möglichkeiten, die dieses Plugin erlaubt:
11 11  
... ... @@ -56,7 +56,7 @@
56 56  
57 57  Im Folgenden wird der Aufbau des HTTP-Requests beschrieben, um ein Plugin zu installieren, zu aktualisieren oder zu löschen.
58 58  
59 -Es muss immer ein HTTP-Post-Request verwendet werden und [[sich an folgende URL richten>>doc:Formcycle.PluginDevelopment.Types.IPluginServletAction]] (Namen des FORMCYCLE-Servers entsprechend anpassen):
61 +Es muss immer ein HTTP-Post-Request verwendet werden und [[sich an folgende URL richten>>doc:Formcycle.PluginDevelopment.Types.IPluginServletAction]] (Namen des {{formcycle/}}-Servers entsprechend anpassen):
60 60  
61 61  {{code language="none"}}
62 62  POST http://localhost:8080/formcycle/plugin?name=deploy-plugin&client-id=154 HTTP/1.1
... ... @@ -95,16 +95,16 @@
95 95  :; plugin-ident=id
96 96  :: //plugin-identifier// muss die gewünschte ID des Plugins enthalten, etwa //53// oder /893//.//
97 97  :; plugin-ident=name
98 -:: //plugin-identifier// muss den gewünschten Names des Plugins enthalten, etwa //my-plugin.jar// oder /foobar.jar//.//
100 +:: //plugin-identifier// muss den gewünschten Names des Plugins enthalten, etwa //my-plugin.jar// oder //foobar.jar//.
99 99  :; plugin-ident=uuid
100 100  :: //plugin-identifier// muss die gewünschte UUID des Plugins enthalten, etwa //03022599-903d-429b-9822-80a324a542fc//.
101 -Andernfalls wird das Plugin installiert, falls noch nicht vorhanden, oder aktualisiert, falls vorhanden.
102 102  ; clear-properties
103 -: Entweder //true// oder //false//. Wenn //true//, werden alle Plugin-Eigenschaften entfernt beziehungsweise deren Werte geleert. Dies wird ausgeführt, bevor die neu zu setzenden Plugin-Eigenschaften (Parameter ///property//) angewendet werden.
104 +: Entweder //true// oder //false//. Wenn //true//, werden alle Plugin-Eigenschaften entfernt beziehungsweise deren Werte geleert. Dies wird ausgeführt, bevor die neu zu setzenden Plugin-Eigenschaften (Parameter //property//) angewendet werden.
104 104  ; property
105 105  : Name und Wert einer Plugin-Eigenschaft, die an der Plugin-Konfiguration gesetzt werden soll, im Format //key=value//. Dieser HTTP-Parameter kann mehrfach angegeben werden, um mehrere Plugin-Eigenschafte zu setzen. Wird etwa //database.username=max// übergeben, wird die Plugin-Eigenschaft //database.username// auf //max// gesetzt.
106 106  ; disallow-install
107 -: Entweder //true// oder //false//. Ist diese Option auf //true// gesetzt und existiert das Plugin noch nicht (bezüglich der angegebenen //plugin-ident// und //plugin-identifier//), wird das Plugin nicht neu installiert und eine Fehlermeldung zurückgegeben. ; locale
108 +: Entweder //true// oder //false//. Ist diese Option auf //true// gesetzt und existiert das Plugin noch nicht (bezüglich der angegebenen //plugin-ident// und //plugin-identifier//), wird das Plugin nicht neu installiert und eine Fehlermeldung zurückgegeben. Andernfalls wird das Plugin installiert, falls noch nicht vorhanden, oder aktualisiert, falls vorhanden.
109 +; locale
108 108  : Die Sprache, welche während der Installation, Aktualisierung oder Löschung des Plugins verwendet werden soll, etwa //en// oder //de//. Beeinflusst nur einige Fehlermeldungen und kann in der Regel weggelassen werden.
109 109  
110 110  === Deploy-Action ===
... ... @@ -112,7 +112,7 @@
112 112  Der Wert des Parameters //deploy-action// gibt an, was genau mit dem Plugin geschehen soll. Es gibt dabei die folgenden Möglichkeiten:
113 113  
114 114  ; save
115 -: Überträgt das angegebene Plugin auf das FORMCYCLE-System. Es muss hierbei eine JAR-Datei übertragen werden. Falls das Plugin noch nicht existiert (und der Parameter //disallow-install// nicht gesetzt ist), wird das Plugin neu installiert und ist dann aktiviert. Andernfalls, falls das Plugin bereits existiert, wird es aktualisiert, dabei bleibt das Plugin aktiviert oder deaktiviert.
117 +: Überträgt das angegebene Plugin auf das {{formcycle/}}-System. Es muss hierbei eine JAR-Datei übertragen werden. Falls das Plugin noch nicht existiert (und der Parameter //disallow-install// nicht gesetzt ist), wird das Plugin neu installiert und ist dann aktiviert. Andernfalls, falls das Plugin bereits existiert, wird es aktualisiert, dabei bleibt das Plugin aktiviert oder deaktiviert.
116 116  
117 117  (((
118 118  {{code language="bash"}}
... ... @@ -174,6 +174,7 @@
174 174  
175 175  ; update-properties
176 176  : Aktualisiert die Eigenschaften des angegebenen Plugins. Es darf hierbei keine JAR-Datei übertragen werden. Entweder die Eigenschaft //clear-properties// oder //property// sollte gesetzt sein. Existiert das angegebene Plugin nicht, wird ein Fehler zurückgegeben. Beispiel:
179 +
177 177  (((
178 178  {{code language="bash"}}
179 179  # Löscht alle vorhandenen Plugin-Eigenschaften und setzt dann die Eigenschaft "foo" auf den Wert "bar"
... ... @@ -297,24 +297,24 @@
297 297  
298 298  {{code language="json"}}
299 299  {
300 - "success": true,
301 - "requestParameters": {
302 - "plugin-ident": ["manifest"],
303 - "name": ["deploy-plugin"],
304 - "client-id": ["1"],
305 - "deploy-action": ["save"],
306 - "plugin-identifier": ["Implementation-Title=com.example:plugin"],
307 - "token": ["admin"]
308 - },
309 - "details": {
310 - "name": "my-plugin.jar",
311 - "active": true,
312 - "id": 203,
313 - "message": "Plugin saved successfully.",
314 - "uuid": "2fe3e1ba-cb32-434e-9f59-4422f8dabcad"
315 - },
316 - "message": "Plugin saved successfully.",
317 - "statusCode": 200
303 + "success": true,
304 + "requestParameters": {
305 + "plugin-ident": ["manifest"],
306 + "name": ["deploy-plugin"],
307 + "client-id": ["1"],
308 + "deploy-action": ["save"],
309 + "plugin-identifier": ["Implementation-Title=com.example:plugin"],
310 + "token": ["admin"]
311 + },
312 + "details": {
313 + "name": "my-plugin.jar",
314 + "active": true,
315 + "id": 203,
316 + "message": "Plugin saved successfully.",
317 + "uuid": "2fe3e1ba-cb32-434e-9f59-4422f8dabcad"
318 + },
319 + "message": "Plugin saved successfully.",
320 + "statusCode": 200
318 318  }
319 319  {{/code}}
320 320  
... ... @@ -322,21 +322,21 @@
322 322  
323 323  {{code language="json"}}
324 324  {
325 - "success": false,
326 - "requestParameters": {
327 - "plugin-ident": ["manifest"],
328 - "name": ["deploy-plugin"],
329 - "client-id": ["1"],
330 - "deploy-action": ["delete"],
331 - "plugin-identifier": ["Implementation-Title=com.example:plugin"],
332 - "token": ["admin"]
333 - },
334 - "details": {
335 - "exceptionType": "java.lang.IllegalArgumentException",
336 - "exceptionMessage": "Deploy action 'delete' requires an existing pluign, but none was found."
337 - },
338 - "message": "class java.lang.IllegalArgumentException: Deploy action 'delete' requires an existing pluign, but none was found.",
339 - "statusCode": 404
328 + "success": false,
329 + "requestParameters": {
330 + "plugin-ident": ["manifest"],
331 + "name": ["deploy-plugin"],
332 + "client-id": ["1"],
333 + "deploy-action": ["delete"],
334 + "plugin-identifier": ["Implementation-Title=com.example:plugin"],
335 + "token": ["admin"]
336 + },
337 + "details": {
338 + "exceptionType": "java.lang.IllegalArgumentException",
339 + "exceptionMessage": "Deploy action 'delete' requires an existing pluign, but none was found."
340 + },
341 + "message": "class java.lang.IllegalArgumentException: Deploy action 'delete' requires an existing pluign, but none was found.",
342 + "statusCode": 404
340 340  }
341 341  {{/code}}
342 342  
... ... @@ -343,7 +343,7 @@
343 343  
344 344  == Create-Token-Servlet ==
345 345  
346 -Mit diesem Servlet kann ein Hash für ein bestimmtes Klartextpasswort erzeugt werden, welcher dann in der Plugin-Eigenschaft //token// hinterlegt werden kann. Es muss hierbei ein HTTP-GET-Request verwendet werden (Pfad auf den FORMCYCLE-Servet und die Mandant-ID entsprechend ersetzen):
349 +Mit diesem Servlet kann ein Hash für ein bestimmtes Klartextpasswort erzeugt werden, welcher dann in der Plugin-Eigenschaft //token// hinterlegt werden kann. Es muss hierbei ein HTTP-GET-Request verwendet werden (Pfad auf den {{formcycle/}}-Servet und die Mandant-ID entsprechend ersetzen):
347 347  
348 348  {{code language="none"}}
349 349  http://localhost:8080/formcycle/plugin?client-id=1&name=create-token&token=<PASSWORT>&method=<METHOD>
... ... @@ -358,26 +358,26 @@
358 358  
359 359  {{code language="json"}}
360 360  {
361 - "success": true,
362 - "requestParameters": {
363 - "name": ["create-token"],
364 - "client-id": ["1"],
365 - "token": ["admin"]
366 - },
367 - "details": {
368 - "method": "sha256",
369 - "token": "sha256:S+32GI3fWXwHHulUMtWmjpQ15EqMvgVYguuO9SKxfNw+ckAGQljP6tKlf1EITnU7"
370 - },
371 - "message": "Hash token created successfully",
372 - "statusCode": 200
364 + "success": true,
365 + "requestParameters": {
366 + "name": ["create-token"],
367 + "client-id": ["1"],
368 + "token": ["admin"]
369 + },
370 + "details": {
371 + "method": "sha256",
372 + "token": "sha256:S+32GI3fWXwHHulUMtWmjpQ15EqMvgVYguuO9SKxfNw+ckAGQljP6tKlf1EITnU7"
373 + },
374 + "message": "Hash token created successfully",
375 + "statusCode": 200
373 373  }
374 374  {{/code}}
375 375  
376 376  == Maven-Deploy-Plugin ==
377 377  
378 -Um ein Plugin nach dem Bauen über Maven in FORMCYCLE hochzuladen, gibt es auch ein Maven-Plugin, welches das Deploy-Servlet anspricht. Dieses ist über die Artifactory von XIMA erhältlich, falls man die entsprechenden Rechte hierfür hat:
381 +Um ein Plugin nach dem Bauen über Maven in {{formcycle/}} hochzuladen, gibt es auch ein Maven-Plugin, welches das Deploy-Servlet anspricht. Dieses ist über die Artifactory von XIMA erhältlich, falls man die entsprechenden Rechte hierfür hat:
379 379  
380 -=== Konfiguration
383 +=== Konfiguration ===
381 381  
382 382  {{code language="xml"}}
383 383  <plugin>
... ... @@ -431,9 +431,9 @@
431 431  ; clearProperties [Standardwert: //false//]
432 432  : Löscht die Werte aller Plugin-Eigenschaften. Entspricht dem Parameter //clear-properties// des Deploy-Plugins, siehe oben.
433 433  ; properties
434 -: Key-Value-Paare mit Eigenschaften, die an dem Plugin gesetzt werden sollen. Entspricht dem Parameter //clear-properties// des Deploy-Plugins, siehe oben.
437 +: Key-Value-Paare mit Eigenschaften, die an dem Plugin gesetzt werden sollen. Entspricht dem Parameter //property// des Deploy-Plugins, siehe oben.
435 435  
436 -=== Empfehlung für Plugin-Projekt
439 +=== Empfehlung für Plugin-Projekt ===
437 437  
438 438  Während das Plugin zahlreiche Einstellunsgmöglichkeiten anbietet, reichen meist die Standardwerte aus. Empfohlen wird das folgende Vorgehen bei der Entwicklung von Plugin-Projekten.
439 439  
... ... @@ -440,111 +440,111 @@
440 440  Folgendes Schnippsel sollte in der Profil-Sektion der //pom.xml// eingefügt werden:
441 441  
442 442  {{code language="xml"}}
443 - <properties>
444 - <fc-deploy-plugin-maven-plugin.version>1.1.0</fc-deploy-plugin-maven-plugin.version>
445 - </properties>
446 + <properties>
447 + <fc-deploy-plugin-maven-plugin.version>1.1.0</fc-deploy-plugin-maven-plugin.version>
448 + </properties>
446 446  
447 - <profiles>
448 - <profile>
449 - <id>fc-deploy</id>
450 - <activation>
451 - <property>
452 - <name>fcDeployUrl</name>
453 - </property>
454 - </activation>
455 - <build>
456 - <plugins>
457 - <plugin>
458 - <groupId>de.xima.fc.maven.plugin</groupId>
459 - <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
460 - <version>${fc-deploy-plugin-maven-plugin.version}</version>
461 - <executions>
462 - <execution>
463 - <goals>
464 - <goal>install</goal>
465 - </goals>
466 - </execution>
467 - </executions>
468 - </plugin>
469 - </plugins>
470 - </build>
471 - </profile>
472 - </profiles>
450 + <profiles>
451 + <profile>
452 + <id>fc-deploy</id>
453 + <activation>
454 + <property>
455 + <name>fcDeployUrl</name>
456 + </property>
457 + </activation>
458 + <build>
459 + <plugins>
460 + <plugin>
461 + <groupId>de.xima.fc.maven.plugin</groupId>
462 + <artifactId>fc-deploy-plugin-maven-plugin</artifactId>
463 + <version>${fc-deploy-plugin-maven-plugin.version}</version>
464 + <executions>
465 + <execution>
466 + <goals>
467 + <goal>install</goal>
468 + </goals>
469 + </execution>
470 + </executions>
471 + </plugin>
472 + </plugins>
473 + </build>
474 + </profile>
475 + </profiles>
473 473  {{/code}}
474 474  
475 475  Das Plugin wird dann anhand des Eintrags //Implementation-Title// im Manifest identifiziert. Hierzu muss der Wert korrekt im Manifest gesetzt werden. Dies kann entweder über das maven-jar-plugin oder über das maven-assembly-plugin geschehen, je nachdem, welches von diesen im Plugin-Projekt genutzt wird:
476 476  
477 477  {{code language="xml"}}
478 - <properties>
479 - <xfc.version>6.4.0-SNAPSHOT</xfc.version>
480 - <maven-jar-plugin.version>3.2.0</maven-jar-plugin.version>
481 - <maven-assembly-plugin.version>3.2.0</maven-assembly-plugin.version>
482 - </properties>
481 + <properties>
482 + <xfc.version>6.4.0-SNAPSHOT</xfc.version>
483 + <maven-jar-plugin.version>3.2.0</maven-jar-plugin.version>
484 + <maven-assembly-plugin.version>3.2.0</maven-assembly-plugin.version>
485 + </properties>
483 483  
484 - <build>
485 - <plugins>
487 + <build>
488 + <plugins>
486 486  
487 - <!-- If using the maven-jar-plugin -->
488 - <plugin>
489 - <groupId>org.apache.maven.plugins</groupId>
490 - <artifactId>maven-jar-plugin</artifactId>
491 - <version>${maven-jar-plugin.version}</version>
492 - <configuration>
493 - <outputDirectory>${basedir}</outputDirectory>
494 - <finalName>${project.artifactId}</finalName>
495 - <archive>
496 - <manifest>
497 - <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
498 - </manifest>
499 - <manifestEntries>
500 - <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
501 - <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
502 - <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
503 - <Implementation-Version>${project.version}</Implementation-Version>
504 - <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
505 - </manifestEntries>
506 - </archive>
507 - </configuration>
508 - </plugin>
490 + <!-- If using the maven-jar-plugin -->
491 + <plugin>
492 + <groupId>org.apache.maven.plugins</groupId>
493 + <artifactId>maven-jar-plugin</artifactId>
494 + <version>${maven-jar-plugin.version}</version>
495 + <configuration>
496 + <outputDirectory>${basedir}</outputDirectory>
497 + <finalName>${project.artifactId}</finalName>
498 + <archive>
499 + <manifest>
500 + <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
501 + </manifest>
502 + <manifestEntries>
503 + <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
504 + <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
505 + <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
506 + <Implementation-Version>${project.version}</Implementation-Version>
507 + <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
508 + </manifestEntries>
509 + </archive>
510 + </configuration>
511 + </plugin>
509 509  
510 510   <!-- If using the maven-assembly-plugin -->
511 - <plugin>
512 - <groupId>org.apache.maven.plugins</groupId>
513 - <artifactId>maven-assembly-plugin</artifactId>
514 - <version>${maven-assembly-plugin.version}</version>
515 - <executions>
516 - <execution>
517 - <id>fat-jar</id>
518 - <phase>package</phase>
519 - <goals>
520 - <goal>single</goal>
521 - </goals>
522 - <configuration>
523 - <outputDirectory>${basedir}</outputDirectory>
524 - <finalName>${project.artifactId}</finalName>
525 - <descriptorRefs>
526 - <descriptorRef>jar-with-dependencies</descriptorRef>
527 - </descriptorRefs>
528 - <appendAssemblyId>false</appendAssemblyId>
529 - <archive>
530 - <manifestEntries>
531 - <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
532 - <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
533 - <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
534 - <Implementation-Version>${project.version}</Implementation-Version>
535 - <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
536 - </manifestEntries>
537 - </archive>
538 - </configuration>
539 - </execution>
540 - </executions>
541 - </plugin>
514 + <plugin>
515 + <groupId>org.apache.maven.plugins</groupId>
516 + <artifactId>maven-assembly-plugin</artifactId>
517 + <version>${maven-assembly-plugin.version}</version>
518 + <executions>
519 + <execution>
520 + <id>fat-jar</id>
521 + <phase>package</phase>
522 + <goals>
523 + <goal>single</goal>
524 + </goals>
525 + <configuration>
526 + <outputDirectory>${basedir}</outputDirectory>
527 + <finalName>${project.artifactId}</finalName>
528 + <descriptorRefs>
529 + <descriptorRef>jar-with-dependencies</descriptorRef>
530 + </descriptorRefs>
531 + <appendAssemblyId>false</appendAssemblyId>
532 + <archive>
533 + <manifestEntries>
534 + <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
535 + <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
536 + <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
537 + <Implementation-Version>${project.version}</Implementation-Version>
538 + <formcycle-version-requirement>${xfc.version}</formcycle-version-requirement>
539 + </manifestEntries>
540 + </archive>
541 + </configuration>
542 + </execution>
543 + </executions>
544 + </plugin>
542 542  
543 - </plugins>
544 - </build>
546 + </plugins>
547 + </build>
545 545  {{/code}}
546 546  
547 -Nun kann das Plugin über Maven gebaut und hochgeladen werden. Die URL auf FORMCYCLE, die Mandant-ID und das Token (Passwort) wird dynamisch über Parameter an Maven übergeben:
550 +Nun kann das Plugin über Maven gebaut und hochgeladen werden. Die URL auf {{formcycle/}}, die Mandant-ID und das Token (Passwort) wird dynamisch über Parameter an Maven übergeben:
548 548  
549 549  {{code language="bash"}}
550 550  mvn clean install -DfcDeployUrl="http://localhost:8080/xima-formcycle" -DfcDeployClientId="1" -DfcDeployToken="admin"

Navigation

Copyright 2000-2025