Best Practice für das Hinzufügen einer Java-Abhängigkeit zu Mendix

Meine Reise mit Mendix begann vor mehr als vier Jahren. Aufgrund der Natur meiner Mendix-Projekte musste ich oft Java-Bibliotheken von Drittanbietern verwenden. Basierend auf dieser Erfahrung schrieb ich vor zwei Jahren einen Blogbeitrag über die Verwaltung von Java-Abhängigkeiten für Mendix-Module

Das Ziel dieses Blog-Beitrags ist es also, meine Erkenntnisse und Best Practices für das Hinzufügen einer Java-Bibliothek zu einem Mendix-Projekt zu dokumentieren und zu sehen, wie sie in einem praktischen Beispiel angewendet werden können.

Aufgeregt? Los geht's!

Beste Vorgehensweise

Dies ist in gewisser Weise die gleiche Botschaft wie in meinem letzten Blogbeitrag. Wie Sie jedoch in der folgenden Liste sehen werden, kann die Liste der Vorteile dieses Ansatzes erheblich erweitert werden, wenn Sie die Dinge etwas anders angehen. Hier ist eine Liste von Vorteilen, die sich aus der Anwendung des oben beschriebenen Prozesses ergeben:

1. Automatischer Umgang mit transitiven Abhängigkeiten.
   Fast jede Java-Bibliothek hat andere Java-Bibliotheken, von denen sie abhängt. Diese einzeln herunterzuladen ist mühsam, fehleranfällig und nicht wartbar. Gradle und Maven unterstützen beide von Haus aus Abhängigkeitsmanagement. Sie finden und laden die richtigen Abhängigkeiten für die Bibliothek herunter, die Sie verwenden möchten. Da sich alle Abhängigkeiten in einem Jar befinden, werden nicht mehr benötigte Abhängigkeiten beim Build automatisch entfernt, was einen einfachen Update-Prozess ermöglicht, im Gegensatz zu vielen Mendix-Modulen, bei denen die Entwickler bei einem Upgrade aufgefordert werden, unbenutzte oder alte Abhängigkeiten manuell zu löschen.
   
   
2. Vermeiden Sie Versionskonflikte bei transitiven Abhängigkeiten. Leider kann der Mendix Java Class Loader, der auf OSGI basiert, nicht mit mehreren Versionen einer Abhängigkeit umgehen. Dies kann zu Blockaden führen, wenn die Bibliothek, die Sie verwenden möchten, eine bestimmte Version einer Abhängigkeit laden muss, während die Mendix-Laufzeit oder ein anderes Mendix-Modul eine andere Version derselben Abhängigkeit verwendet. Dank des Shadow-Plugins können solche Abhängigkeiten überlagert werden, so dass der Classloader sie gleichzeitig laden kann.
   
   
3. Lernen Sie die Java-Bibliothek isoliert kennen.
   Die Verwendung einer Bibliothek eines Drittanbieters, mit der Sie nicht vertraut sind, ist schon schwierig genug. Der Versuch, dies im Kontext eines großen Mendix-Projekts zu tun, ist tausendmal schwieriger. Wenn etwas nicht funktioniert, ist es unmöglich zu sagen, ob der Fehler von der Bibliothek, Ihrem Java-Code, der Integration zwischen Mendix und Java oder der Mendix-Anwendung selbst kommt. Auch das Testen und Debuggen ist komplizierter und zeitaufwändiger, wenn Sie jedes Mal eine Mendix-Laufzeit starten müssen.
   
   
4. Kodieren Sie für die Schnittstelle, die Sie wollen.
   Oftmals hat die Java-Bibliothek eine komplizierte Schnittstelle. Um etwas so einfaches wie einen Funktionsaufruf durchzuführen, müssen Sie wahrscheinlich die üblichen Verdächtigen durchlaufen: Factories, Builder und Manager, bis Sie ein Objekt haben, mit dem Sie die Methode tatsächlich aufrufen können. Am besten ist es, diese Komplexität auszublenden und einen einfachen Adapter/Fassade zu bauen, der die Schnittstelle hat, die Sie wollen und brauchen. Ein zusätzlicher Bonus ist, dass Sie die Bibliothek eines Drittanbieters gegen eine andere austauschen können, ohne die Mendix-Anwendung berühren zu müssen.
   
   
5. Einfaches Einrichten von Unit-Tests, die als Regressionssuite dienen.
   Dies ist so wichtig, dass ich es in dieser Liste zehnmal wiederholen möchte. Wenn etwas in einer komplexen Anwendung nicht funktioniert, ist es sehr schwer, den genauen Ort des Fehlers zu lokalisieren. Mit Hilfe von Tests können Sie sehr einfach überprüfen, ob das Problem in der Bibliothek eines Drittanbieters oder irgendwo anders in Ihrer Mendix-Logik liegt. Ein weiterer guter Grund für Tests ist es, die Risiken zu reduzieren, die mit Änderungen an Ihrem Code oder dem Upgrade der Bibliothek auf eine neue Version verbunden sind. Theoretisch könnten Sie dies in Mendix tun, aber das ist viel komplizierter, ressourcen- und zeitintensiver und schwieriger in Ihren Build-Prozess zu integrieren als mit Gradle oder Maven.
   
   
6. Separate Versionskontrolle.
   Dies ist ein kleiner Punkt, aber ich bevorzuge es wirklich, die Abhängigkeiten in separaten Repositories zu halten. Außerdem können Sie ein anderes Versionskontrollsystem (git) verwenden, da Sie nicht durch Mendix (svn) eingeschränkt sind. Und git hat bereits gute Vorlagen für die Ignorierlisten von gradle und maven.

Schritt-für-Schritt-Anleitung

Um die obige Best Practice zu untermauern, gehen wir die Schritte für das Hinzufügen einer konkreten Drittanbieter-Bibliothek durch. Wie wäre es mit einem Markdown-Parser? Das eine Modul

Das Ziel ist es, diese Bibliothek in einem Mendix-Projekt zu verwenden, um einen Markdown-Text in HTML zu konvertieren. Das Endergebnis sollte in etwa so

Voraussetzungen

Ich werde Gradle für diese Anleitung verwenden. Maven kann genau dasselbe tun.

Gradle v5.5: kann mit Hilfe des offiziellen Tutorials installiert werden .

Schritt 1: Initialisieren des Projekts

Erstellen Sie ein neues Git-Projekt in einem leeren Verzeichnis. Öffnen Sie dann ein Befehlszeilenfenster und geben Sie ein:

gradle init

Damit wird der Prozess der Einrichtung eines gradle-Projekts gestartet. Folgen Sie den Anweisungen und wählen Sie sorgfältig aus. Ich empfehle die unten stehenden Optionen, aber vielleicht haben Sie andere Präferenzen:

• Projekttyp: 3: Bibliothek (keine Notwendigkeit für eine main-Methode)
• Sprache: 3: java
• Build-Skript: 1: groovy
• Test-Framework: 1: JUnit4

Nach Beendigung des init-Befehls

Einige wichtige Stellen, die wir verwenden werden, sind:

• src \ main - hier kommt der Java-Code hin
• src \ test - hier kommt der Testcode hin
• build.gradle - Abhängigkeiten, Plugins und mehr definieren

Schritt 2: Hinzufügen einer Abhängigkeit über gradle

Am einfachsten ist es, das Maven Repository aufzurufen und nach der Abhängigkeit zu suchen, die Sie hinzufügen möchten. Auf dieser Seite befindet sich ein Code-Snippet mit dem Befehl, den Sie verwenden können, um diese Abhängigkeit

compile Gruppe: 'com.vladsch.flexmark', Name: 'flexmark-all', Version: '0.62.2'

Kopieren Sie diesen Codeschnipsel und fügen Sie ihn der Datei build.gradle unter dependencies

Schritt 3: Schreiben und Implementieren einer Schnittstelle zur Bibliothek eines Drittanbieters

Schließlich ist es an der Zeit, etwas Code zu schreiben. Sie können einen beliebigen Editor oder eine IDE verwenden, aber ich habe festgestellt, dass IntelliJ am zuverlässigsten mit gradle funktioniert. Das ist wichtig, denn ohne den Klassenpfad aufzulösen, um die Gradle-Abhängigkeiten zu finden, wird Ihr Code nicht kompiliert und wird viele Fehler auslösen (und keine Autovervollständigung).

Im Folgenden finden Sie eine einfache Schnittstelle zur Konvertierung von Markdown in HTML und eine Klasse, die diese implementiert (die ich größtenteils von hier

Paket flexmark.mendix;

importieren com.vladsch.flexmark.html.HtmlRenderer;
importieren com.vladsch.flexmark.parser.Parser;
importieren com.vladsch.flexmark.util.ast.Knoten;
importieren com.vladsch.flexmark.util.data.MutableDataSet;

public interface MarkdownToHTMLConverter {

// Hauptmethode
String convert(String markdown);

// factory method
static MarkdownToHTMLConverter create() {
return new FlexmarkConverter();
}}class


FlexmarkConverter implements MarkdownToHTMLConverter {

@Override
public String convert(String markdown) {
MutableDataSet options = new MutableDataSet();
Parser parser = Parser.builder(options).build();
HtmlRenderer renderer = HtmlRenderer.builder(options).build();
Node document = parser.parse(markdown);
String html = renderer.render(document);
return html;
}}




















































Schritt 4: Schreiben von Unit-Tests

Da dies ein Bibliotheksprojekt ist, hat es keine Hauptklasse. Der einfachste Weg zu überprüfen, ob etwas funktioniert, ist das Schreiben eines Tests. Das ist eigentlich perfekt, weil es uns dazu zwingt, Tests zu schreiben, die wir verwenden können, wenn wir in der Zukunft Änderungen vornehmen, um zu überprüfen, ob alles korrekt funktioniert.

Für den Zweck dieses Beitrags werde ich einen einzigen einfachen Test hinzufügen. Für den produktiven Einsatz sollten Sie sicherstellen, dass Ihre Tests alle Aspekte der Bibliothek abdecken, die Sie verwenden wollen, und realistische Angaben enthalten. Aber übertreiben Sie es nicht, denn das Ziel ist nicht, die Bibliothek selbst zu testen, da sie wahrscheinlich bereits gut getestet ist.

package flexmark.mendix;

import org.junit.Assert;
import org.junit.Test;

public class MarkdownToHTMLConverterTest {

@Test public void basicTest() {
MarkdownToHTMLConverter converter = MarkdownToHTMLConverter.createConverter();
Assert.assertEquals("

Dies ist Sparta

\n", converter.convert("Dies ist *Sparta*"));
}

}

Der Test kann von IntelliJ aus gestartet werden, indem Sie auf die kleine grüne Schaltfläche Ausführen

Schritt 5: Erstellen eines Fat Jar

Diese Funktion ist nicht standardmäßig in gradle enthalten, daher müssen wir zuerst ein gradle Plugin installieren.

Fügen Sie den folgenden Codeschnipsel am Anfang derbuild.gradle Datei unter plugins

id 'com.github.johnrengelman.shadow' version '5.1.0'

Damit wird das Plugin dem Projekt hinzugefügt und wir können neue Befehle mit gradle verwenden. Geben Sie in einem Kommandozeilenfenster ein:

gradle shadowJar

Dadurch wird eine einzelne jar-Datei erzeugt, die alle Abhängigkeiten unter build\\libs\\

Schritt 6: Shadowing

Shadowing ist der Prozess der Umbenennung von Java-Paketen auf Byte-Code-Ebene, um die Verwendung von zwei Paketen mit demselben Namen in einer Java-Anwendung zu ermöglichen. Dies wird in der Regel gemacht, um Versionskonflikte zwischen zwei verschiedenen Versionen eines Pakets zu vermeiden. In gradle können Pakete durch Hinzufügen des folgenden Schnipsels am Ende der build. gradle-Datei beschattet werden .

shadowJar { relocate 'org.apache', 'flexmark.mendix.org.apache' }

Dadurch werden alle Java-Pakete, die mit org.apache beginnen, in flexmark.mendix.org.apache umbenannt .

Um für die Zukunft gerüstet zu sein, ist es am besten, alle Abhängigkeiten zu überwachen, auch solche, die heute keine Probleme verursachen. Mehrere Abhängigkeiten können durch das Hinzufügen mehrerer relocate-Zeilen

Leider kann das Shadowing keine Bibliotheken behandeln, die auf Reflection beruhen. Wenn Sie also auf ein Problem beim Laden von Klassen stoßen, kann es notwendig sein, das Shadowing der schuldigen Bibliotheken aufzuheben.

Schritt 7: Verwendung der Bibliothek in Mendix

Kopieren Sie das fat jar von build\\libs\\ in Ihr Mendix-Projektverzeichnis in den userlib-Ordner

Erstellen Sie dann eine Mendix-Java-Aktion, damit die Java-Bibliothek von einem Microflow aus aufgerufen werden kann. Die Anzahl und Art der Parameter und Rückgabewerte variiert je nach Anwendungsfall. Das Design von guten Java-Aktionen verdient wahrscheinlich einen eigenen Blogbeitrag. Hier werde ich nur einen Trick erwähnen:

Benennen Sie die Parameter mit einem Unterstrich am Ende. Dies verhindert ein bekanntes Mendix-Problem, bei dem ein Parametername, der ein reserviertes Wort ist, in Java als Suffix verwendet wird. Der Unterstrich verhindert dies und ist beim Aufruf der Java-Aktion in einem Microflow nicht sichtbar.

Rufen Sie schließlich die Schnittstelle, die in Schritt 3 kodiert wurde, von der Java-Aktion aus auf. Da wir eine Fassade verwenden, um die Komplexität der Bibliothek eines Drittanbieters zu verbergen, besteht dieser Teil oft nur aus ein oder zwei Zeilen.

import flexmark.mendix.MarkdownToHTMLConverter;

// DER KÜRZE HALBER WEGGELASSENE ZEILEN

@java.lang.Override
public java.lang.String executeAction() throws Exception
{
// BENUTZERCODE BEGINNEN
MarkdownToHTMLConverter converter = MarkdownToHTMLConverter.create();
return converter.convert(Markdown_);
// ENDE DES BENUTZERCODES
}

Damit ist die Schritt-für-Schritt-Anleitung abgeschlossen. Den gesamten Quellcode finden Sie unter https://github.com/gajduk/flexmark-mendix.

Zusammenfassung

Das Hinzufügen von Java-Bibliotheken zu Mendix kann ziemlich knifflig sein. Wenn man die Dinge einfach in den userlib-Ordner wirft, kann man schnell in Schwierigkeiten geraten. Im Laufe der Jahre bin ich auf viele Probleme gestoßen, die mich dazu gebracht haben, den oben beschriebenen Prozess zu entwickeln.

Mein Prozess ist bei weitem nicht perfekt, wenn Sie also Verbesserungsvorschläge haben, kontaktieren Sie mich bitte über Mendix Slack oder per E-Mail, es wäre toll mehr zu erfahren.

Wie sieht Ihr Prozess für das Hinzufügen von Drittanbieter-Abhängigkeiten aus?

Ich hoffe, dass Ihnen dieser Blogbeitrag gefallen hat und dass er Ihnen hilft, einfacher mit Java-Abhängigkeiten zu arbeiten.