Bewährte Methode zum 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. Aufgrund dieser Erfahrung schrieb ich vor zwei Jahren einen Blogbeitrag über Verwaltung von Java-Abhängigkeiten für Mendix-Module. Seitdem habe ich mehr Einblick in diesen Prozess erhalten und möchte ihn mit Ihnen teilen.

Das Ziel dieses Blogposts 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? Lass uns gehen!

Bewährtes Verfahren

Meiner Meinung nach besteht der beste Weg, Mendix eine Abhängigkeit von Drittanbietern hinzuzufügen, darin, zuerst ein separates reines Java-Projekt (mit Gradle oder Maven) einzurichten, das die Abhängigkeit enthält und eine einfach zu bedienende Oberfläche bietet. Verwenden Sie dann ein Shadow-Plugin, um ein sogenanntes zu generieren fett jar, das alle Abhängigkeiten enthält und das in Ihr Mendix-Projekt importiert.

Dies ist in gewissem Maße dieselbe Botschaft aus meinem vorherigen Blogbeitrag. Wie Sie der folgenden Liste entnehmen können, wenn Sie die Dinge etwas anders angehen, kann die Liste der Vorteile dieses Ansatzes jedoch erheblich erweitert werden. Hier ist eine Liste der Vorteile, die sich aus der Verwendung des oben genannten Verfahrens ergeben:

1. Automatisch mit transitiven Abhängigkeiten umgehen.
2. Fast jede Java-Bibliothek hat andere Java-Bibliotheken, von denen sie abhängt. Sie einzeln herunterzuladen ist umständlich, fehleranfällig und nicht wartbar. Gradle und Maven unterstützen beide sofort das Abhängigkeitsmanagement. Sie werden die richtigen Abhängigkeiten für die Bibliothek, die Sie verwenden möchten, finden und herunterladen. Da sich alle Abhängigkeiten in einem Jar befinden, werden alle Abhängigkeiten, die nicht mehr benötigt werden, beim Build automatisch entfernt. Dies ermöglicht einen einfachen Aktualisierungsprozess im Gegensatz zu so vielen Mendix-Modulen, bei denen Entwickler gebeten werden, ungenutzte oder alte Abhängigkeiten beim Upgrade manuell zu löschen.
4. Vermeiden Sie Versionskonflikte bei transitiven Abhängigkeiten. Leider basiert der Java-Klassenlader von Mendix auf OSGI behandelt nicht mehrere Versionen einer Abhängigkeit. Dies kann ein Blockierungsproblem sein, 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 überschattet werden, sodass der Klassenlader sie gleichzeitig laden kann.
5. Lernen Sie die Java-Bibliothek isoliert kennen.
6. Die Verwendung einer Bibliothek eines Drittanbieters, mit der Sie nicht vertraut sind, ist für sich genommen schwierig genug. Der Versuch, dies im Rahmen 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-App selbst herrührt. Auch das Testen und Debuggen ist komplizierter und zeitaufwändiger, wenn Sie jedes Mal eine Mendix-Laufzeit starten müssen.
8. Code für die gewünschte Schnittstelle.
9. Oft verfügt die Java-Bibliothek über eine komplizierte Benutzeroberfläche. Das ist schließlich Java. Um etwas so Einfaches wie einen Funktionsaufruf zu tun, müssen Sie wahrscheinlich die übliche Liste von Verdächtigen durchgehen: Fabriken, Builder und Manager, bis Sie ein Objekt haben, für das Sie die Methode tatsächlich aufrufen können. Es ist am besten, diese Komplexität zu verbergen und einen einfachen Adapter/eine einfache Fassade zu bauen, die über die gewünschte und benötigte Schnittstelle verfügt. Ein zusätzlicher Bonus ist, dass Sie die Drittanbieter-Bibliothek gegen eine andere austauschen können, ohne die Mendix-Anwendung berühren zu müssen.
11. Richten Sie auf einfache Weise Komponententests ein, die als Regressionssuite dienen.
12. Das ist so wichtig, dass ich es in dieser Liste zehnmal wiederholen möchte. Wenn in einer komplexen App etwas nicht funktioniert, ist es sehr schwierig, den genauen Ort des Fehlers zu bestimmen. Mit einigen Tests können Sie also auf sehr einfache Weise überprüfen, ob das Problem in der Bibliothek eines Drittanbieters oder an einer anderen Stelle in Ihrer Mendix-Logik liegt. Ein weiterer guter Grund für Tests besteht darin, die Risiken zu reduzieren, die mit Änderungen an Ihrem Code oder der Aktualisierung 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 Gradle oder Maven.
14. Separate Versionskontrolle.
15. Dies ist ein kleiner Punkt, aber ich bevorzuge es wirklich, die Abhängigkeiten in separaten Repositorys aufzubewahren. 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 Gradle- und Maven-Ignorierlisten.

Anleitung Schritt für Schritt

Um die oben genannten Best Practices fundierter zu gestalten, gehen wir die Schritte zum Hinzufügen einer konkreten Drittanbieterbibliothek durch. Wie wäre es mit einem Markdown-Parser ? Das eine Modul im Mendix App Store zum Thema Markdown-Konvertierung ist jetzt 7 Jahre alt und verwendet eine veraltete Bibliothek, die nicht mehr gepflegt wird. Das wäre also ein nettes Upgrade.

Ziel ist es, diese Bibliothek in einem Mendix-Projekt zu verwenden, um Markdown-Text in HTML zu konvertieren.

Voraussetzungen

Ich werde Gradle für diesen Leitfaden verwenden. Maven kann genau das Gleiche tun.

Gradle v5.5: kann installiert werden, indem Sie dem folgen offizielles Tutorial . Neuere oder ältere Versionen sollten ebenfalls funktionieren, aber diese wird in diesem Tutorial verwendet. Es ist ein Befehlszeilentool, das sich um das Management, das Shadowing und das Erstellen von Abhängigkeiten kümmert.

Schritt 1: Initialisieren Sie das Projekt

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

Gradle Init

Dadurch wird der Prozess der Einrichtung eines Gradle-Projekts gestartet. Folgen Sie den Anweisungen und wählen Sie sorgfältig aus. Ich empfehle die folgenden Optionen, aber Sie haben möglicherweise andere Präferenzen:

• Projekttyp: 3: Bibliothek (keine Hauptmethode erforderlich)
• Sprache: 3: Java
• Build-Skript: 1: groovy
• Testframework: 1: JUnit4

Sobald der initiieren Der Befehl ist abgeschlossen, er hätte eine Projektdateistruktur generiert, die der folgenden ähnelt:

Einige wichtige Orte, die wir nutzen werden, sind:

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

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

Der einfachste Weg, dies zu tun, besteht darin, zum Maven Repository zu gehen und nach der Abhängigkeit zu suchen, die Sie hinzufügen möchten. Das ist zum Beispiel Flexmark-Abhängigkeit Auf dieser Seite gibt es einen Codeausschnitt mit dem Befehl, mit dem Sie diese Abhängigkeit zu Ihrem Gradle-Projekt hinzufügen können.

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

Kopieren Sie diesen Codeausschnitt und fügen Sie ihn dem build.gradle Datei unter Abhängigkeiten. Sie können andere Kompilierungsabhängigkeiten entfernen, die Gradle automatisch hinzugefügt hat. Sie dienen nur als Beispiel, aber stellen Sie sicher, dass Sie die Testabhängigkeit beibehalten, da die Tests sonst nicht funktionieren.

Schritt 3: Schreiben und implementieren Sie eine Schnittstelle zur Drittanbieterbibliothek

Endlich ist es an der Zeit, etwas Code zu schreiben. Sie können jeden Editor oder jede IDE verwenden, aber ich habe festgestellt, dass IntelliJ mit Gradle am zuverlässigsten funktioniert. Dies ist wichtig, da Ihr Code nicht kompiliert wird, ohne den Klassenpfad aufzulösen, um die Gradle-Abhängigkeiten zu finden, und viele Fehler auslöst (und keine automatische Vervollständigung).

Unten finden Sie eine einfache Oberfläche zum Konvertieren von Markdown in HTML und eine Klasse, die es implementiert (von der ich hauptsächlich kopiert habe). hier).

paket flexmark.mendix;

importiere com.vladsch.flexmark.html.HtmlRenderer;
importiere com.vladsch.flexmark.parser.Parser;
importiere com.vladsch.flexmark.util.ast.Node;
importiere com.vladsch.flexmark.util.data.MutableDataset;

öffentliche Schnittstelle MarkdownToHtmlConverter {

//Hauptmethode
Zeichenkette konvertieren (Zeichenkettenmarkdown);

//Factory-Methode
statischer MarkdownToHtmlConverter create () {
gibt neuen flexmarkConverter () zurück;
}
}

Klasse FlexMarkConverter implementiert MarkdownToHtmlConverter {

@Override
öffentliche Zeichenkettenkonvertierung (String-Markdown) {
mutableDataset-Optionen = neues mutableDataset ();
Parserparser = Parser.Builder (Optionen) .build ();
HtmlRenderer-Renderer = HtmlRenderer.Builder (Optionen) .build ();
Knotendokument = parser.parse (markdown);
Zeichenfolge html = renderer.render (Dokument);
gib html zurück;
}
}


Beachten Sie, dass Klassen und Interfaces im Allgemeinen nicht in derselben Datei sein sollten, ich habe es nur der Kürze halber gemacht.

Schritt 4: Komponententests schreiben

Da es sich um ein Bibliotheksprojekt handelt, hat es keine Hauptklasse. Der einfachste Weg, um zu überprüfen, ob etwas funktioniert, besteht darin, einen Test zu schreiben. Das ist eigentlich perfekt, weil es uns zwingt, Tests zu schreiben, die wir verwenden können, wenn wir in Zukunft Änderungen vornehmen, um zu überprüfen, ob alles korrekt funktioniert.

Für den Beitrag werde ich einen einzigen einfachen Test hinzufügen. Stellen Sie für den Einsatz in der Produktion sicher, dass Ihre Tests alle Aspekte der Bibliothek abdecken, die Sie verwenden möchten, und realistische Eingaben enthalten. Aber übertreiben Sie es nicht, das Ziel ist nicht, die Bibliothek selbst zu testen, da sie wahrscheinlich bereits gut getestet ist.

paket flexmark.mendix;

importiere org.junit.Assert;
importiere org.junit.Test;

öffentliche Klasse MarkdownToHtmlConverterTest {

@Test public void basicTest () {
MarkdownToHtmlConverter-Konverter = MarkdownToHtmlConverter.createConverter ();
assert.assertEquals (“ <p>Das ist <em>Sparta</em>\n„, converter.convert („Das ist</p> *Sparta*“));
}

}

Der Test kann von IntelliJ aus gestartet werden, indem Sie auf das kleine grüne Symbol klicken Lauf knopf. Wenn die Tests erfolgreich sind, besteht der nächste Schritt darin, die Bibliothek so zu verpacken (zu erstellen), dass sie in unser Mendix-Projekt importiert werden kann.

Schritt 5: Ein Fettglas bauen

Diese Funktion ist mit Gradle nicht sofort einsatzbereit, daher müssen wir zuerst ein Gradle-Plugin installieren.

Fügen Sie das folgende Code-Snippet oben in das build.gradle Datei unter Plugins (über Java)

ID 'com.github.johnrengelman.shadow' Version '5.1.0'

Dadurch wird das Plugin zum Projekt hinzugefügt und wir können neue Befehle mit Gradle verwenden. Geben Sie in einem Befehlszeilenfenster Folgendes ein:

Gradle ShadowJar

Dadurch wird eine einzige JAR-Datei erzeugt, die alle Abhängigkeiten enthält unter \\ libs\\ erstellen. Dieser Vorgang muss jedes Mal wiederholt werden, wenn Sie Änderungen am Code oder an den Abhängigkeiten vornehmen.

Schritt 6: Beschattung

Beim Shadowing werden Java-Pakete auf Bytecode-Ebene umbenannt, sodass zwei Pakete mit demselben Namen in einer Java-App verwendet werden können. Dies geschieht normalerweise, um Versionskonflikte zwischen zwei verschiedenen Versionen eines Pakets zu vermeiden. In Gradle können Pakete überschattet werden, indem das folgende Snippet am Ende des build.gradle Datei.

ShadowJar {'org.apache', 'flexmark.mendix.org.apache' verschieben}

Dadurch werden alle Java-Pakete umbenannt, die mit beginnen org.apache zu flexmark.mendix.org.apache . Um zu bestätigen, dass die Umbenennung funktioniert hat, überprüfen Sie den Inhalt der JAR-Datei mit einem Zip-Inspektor wie 7-Zip.

Um zukunftssicher zu sein, ist es am besten, alle Abhängigkeiten abzubilden, auch solche, die heute vielleicht kein Problem verursachen. Mehrere Abhängigkeiten können überschattet werden, indem mehrere hinzugefügt werden umziehen Linien.

Leider behandelt das Spiegeln keine Bibliotheken, die auf Reflektion angewiesen sind. Wenn Sie also auf ein Problem beim Laden von Klassen stoßen, müssen Sie möglicherweise die schuldigen Bibliotheken entfernen.

Schritt 7: Verwenden der Bibliothek in Mendix

Kopiere das Fettglas von \\ libs\\ erstellen in Ihr Mendix-Projektverzeichnis im Benutzerbibliothek Mappe.

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 variieren je nach Anwendungsfall. Das Entwerfen guter Java-Aktionen verdient wahrscheinlich einen separaten 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 mit einem Suffix versehen wird. Der Unterstrich verhindert dies und ist eigentlich nicht sichtbar, wenn die Java-Aktion in einem Microflow aufgerufen wird.

Rufen Sie abschließend die in Schritt 3 codierte Schnittstelle von der Java-Aktion aus auf. Da wir eine Fassade verwenden, um die Komplexität der Drittanbieter-Bibliothek zu verbergen, besteht dieser Teil oft nur aus ein oder zwei Zeilen.

importiere flexmark.mendix.markdownToHtmlConverter;

//ZEILEN, DIE FÜR BREVITY@java.lang.Overridepublic WEGGELASSEN WURDEN java.lang.String executeAction () löst eine Ausnahme aus {//BEGIN USER codeMarkdownToHtmlConverter converter = markdownToHtmlConverter.create (); return converter.convert (Markdown_);//ENDBENUTZERCODE}

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

Einpacken

Das Hinzufügen von Java-Bibliotheken zu Mendix kann ziemlich schwierig sein. Wenn Sie einfach Dinge in den Userlib-Ordner werfen, werden Sie bestimmt in Schwierigkeiten geraten. Im Laufe der Jahre stieß ich diesbezüglich auf viele Probleme, die mich dazu veranlassten, den oben beschriebenen Prozess zu entwickeln.

Mein Prozess ist jedoch bei weitem nicht perfekt. Wenn Sie also Verbesserungsvorschläge haben, wenden Sie sich bitte per Mendix-Slack oder E-Mail an mich. Es wäre toll, mehr zu erfahren.

Wie gehen Sie vor, um Abhängigkeiten von Drittanbietern hinzuzufügen?

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