Plugin-Entwicklung

Inhalt [ Verbergen ]

Plugins für zusätzliche Funktionalitäten
API-Dokumentation
Maven-Setup
Maven-Projekteinrichtung
Maven-Archetypes
Deploy-Plugin
FC-Server-Plugin

Plugins für zusätzliche Funktionalitäten

Xima® Formcycle bietet ein Vielzahl von Einstiegspunkten für die Erweiterung der Standard-Funktionalitäten durch Plugins. Basierend auf den einzelnen Plugin-Typen werden diese zu gewissen Zeitpunkten automatisch oder manuell angesprochen und erlauben es somit von der Ersetzung eigener Platzhalter bis hin zur Implementierung eigener Verarbeitungslogik Xima® Formcycle anzupassen. Als fundamentaler erster Schritt für die Entwicklung eigener Plugins ist hierbei das Erstellen eines entsprechenden Java-Projekts anzusehen.

API-Dokumentation

Die API-Dokumentation für Xima® Formcycle findet sich hier auf unserer Seite: Javadocs

Maven-Setup

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 zum Einsatz. Andere Build-Tools können prinzipiell benutzt werden, hier können wir aber keine Hilfe bereitstellen.

Um die entsprechenden Abhängigkeiten zu Xima® Formcycle bereitzustellen, ist das Repository unter der 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.

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:

~/.m2/settings.xml

<?xml version="1.0" encoding="UTF-8"?>
<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"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">


<profiles>
   <profile>
     
     <repositories>
       <repository>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
         <id>xima</id>
         <name>libs-release</name>
         <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
       </repository>
     </repositories>
     
     <pluginRepositories>
       <pluginRepository>
         <snapshots>
           <enabled>false</enabled>
         </snapshots>
         <id>xima</id>
         <name>plugins-release</name>
         <url>https://artifactory.xima-services.de/artifactory/fc-plugin-dev</url>
       </pluginRepository>
     </pluginRepositories>
     <id>xima-artifactory</id>
   </profile>
</profiles>


<activeProfiles>
   <activeProfile>xima-artifactory</activeProfile>
</activeProfiles>


<pluginGroups>
   <pluginGroup>de.xima.fc.maven.plugin</pluginGroup>
</pluginGroups>
</settings>

Maven-Projekteinrichtung

Im Folgenden werden einige Punkte beschrieben, die beim Einrichten eines Maven-Projekts für ein Xima® Formcycle-Plugin beachtet werden müssen. Für den schnellen Einstieg gibt auch einige Maven-Archetypes.

Artekfakte und Abhängigkeiten

Alle Abhängigkeiten zu Xima® Formcycle sind im scope "provided" zu definieren!

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.

In der pom.xml des Plugin-Projekts kann diese Abhängigkeit wie folgt eingebunden werden:

  <properties>
   <xfc.version>7.0.10</xfc.version>
</properties>

<dependencies>
   <dependency>
    <groupId>de.xima.fc</groupId>
    <artifactId>fc-plugin-common</artifactId>
    <version>${xfc.version}</version>
    <scope>provided</scope>
   </dependency>
</dependencies>

Ferner steht je nach Tiefe der Integration in die bestehende Umgebung von Xima® Formcycle 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:

  <dependency>
  <groupId>de.xima.fc</groupId>
  <artifactId>fc-logic</artifactId>
  <version>${xfc.version}</version>
  <scope>provided</scope>
</dependency>

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.

Ferner ist zu beachten, dass sämtliche Abhängigkeiten zu Xima® Formcycle 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 Xima® Formcycle benutzten und damit bereitstehenden Bibliotheken wiederverwendet werden (z.B. diverse Apache Commons-Implementierungen).

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 Xima® Formcycle, für die das Plugin gedacht ist.Ist erforderlich, damit Xima® Formcycle bei der Installation die Kompatibilität prüfen kann.
Implementation-Version: 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.
Implementation-Title: Optional, wird standardmäßig etwa vom Deploy-Plugin verwendet, um das Plugin zu identifzieren.

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 Xima® Formcycle sowie anderen Bibliotheken, welche bereits durch Xima® Formcycle 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).

Dies kann entweder über das maven-assembly-plugin oder das 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.

Für einfache Plugins ist das maven-assembly-plugin ausreichend. Dieses kann in der pom.xml wie folgt konfiguriert werden:

maven-assembly-plugin in pom.xml

<properties>
   <maven-assembly-plugin.version>3.3.0</maven-assembly-plugin.version>
</properties>
<build>
   <finalName>${project.parent.artifactId}</finalName>
   <plugins>
     <plugin>
       <groupId>org.apache.maven.plugins</groupId>
       <artifactId>maven-assembly-plugin</artifactId>
       <version>${maven-assembly-plugin.version}</version>
       <executions>
         <execution>
           <id>fat-jar</id>
           <phase>package</phase>
           <goals>
             <goal>single</goal>
           </goals>
           <configuration>
             <finalName>${project.parent.artifactId}</finalName>
             <appendAssemblyId>false</appendAssemblyId>
             <descriptorRefs>
               <descriptorRef>jar-with-dependencies</descriptorRef>
             </descriptorRefs>
             <archive>
               <manifest>
                 <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
               </manifest>
               <manifestEntries>
                 <formcycle-version-requirement>${xfc-version}</formcycle-version-requirement>
                 <Build-Timestamp>${maven.build.timestamp}</Build-Timestamp>
                 <Implementation-Title>${project.groupId}:${project.artifactId}</Implementation-Title>
                 <Implementation-Vendor-Id>${project.groupId}</Implementation-Vendor-Id>
                 <Implementation-Version>${project.version}</Implementation-Version>
               </manifestEntries>
             </archive>
           </configuration>
         </execution>
       </executions>
     </plugin>
   </plugins>
</build>

Bauen und Installieren

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:

mvn clean install

Nachdem das Plugin erfolgreich gebaut wurde, kann die so entstandene JAR-Datei im target-Verzeichnis in Xima® Formcycle über die Oberfläche Mandant-Plugins beziehungsweise System-Plugins hochgeladen werden.

Siehe Deploy-Plugin zum automatischen Hochladen beim Maven-Build.

Siehe FC-Server-Plugin zum Starten eines einfachen Xima® Formcycle-Servers.

Maven-Archetypes

TODO

Um einen besseren Einstieg in die Plugin-Entwicklung zu finden, bieten wir auf unserer Downloadseite

Deploy-Plugin

TODO

FC-Server-Plugin

TODO