Generieren, Bauen und Ausführen von Code
In diesem Kapitel wird erläutert, wie Sie Code anhand eines Mappings und eines Projekts generieren, den generierten Code bauen und ausführen. In manchen Fällen müssen Sie Ihren generierten C++/C#/Java-Code ändern, um ihn in Ihren benutzerdefinierten Code integrieren zu können. Nähere Informationen dazu finden Sie unter Integrieren von generiertem Code.
Generieren von Code anhand eines Mappings
Um Code anhand einer Mapping-Designs (.mfd) zu generieren, gehen Sie folgendermaßen vor:
1.Wählen Sie im Abschnitt Code-Generierung des Dialogfelds Optionen und in den Mapping-Einstellungen die entsprechenden Codegenerierungsoptionen aus (gilt für C# und C++). Nähere Informationen zu den Codegenerierungseinstellungen im Dialogfeld Optionen finden Sie unter Codegenerierung.
2.Klicken Sie auf Datei | Code generieren in und wählen Sie die gewünschte Transformationssprache aus. Klicken Sie alternativ dazu auf Datei | Code in ausgewählter Sprache generieren. In diesem Fall wird der Code in der in der Symbolleiste ausgewählten Sprache generiert.
3.Wählen Sie ein Zielverzeichnis für die generierten Dateien aus und klicken Sie anschließend zur Bestätigung auf OK. MapForce generiert den Code und zeigt das Ergebnis der Operation im Fenster Meldungen an.
Generieren von Code anhand eines Projekts (Projekte (Professional und Enterprise Edition)
Sie können anhand eines Mapping-Projekts (.mfp), das aus mehreren Mapping-Design-Dateien (.mfd) besteht, Code generieren. Beachten Sie, dass alle Mapping-Design-Dateien im Projekt für die Codegenerierung geeignet sein müssen, d.h. alle ihre Komponenten müssen in der ausgewählten Transformationssprache unterstützt werden, wie unter Unterstützte Funktionalitäten im generierten Code beschrieben.
Um Code anhand eines Mapping-Projekts zu generieren, gehen Sie folgendermaßen vor:
1.Öffnen Sie das entsprechende Mapping-Projekt, anhand dessen Sie Code generieren möchten.
2.Klicken Sie mit der rechten Maustaste im Fenster Projekt auf den Projektnamen und wählen Sie im Kontextmenü den Befehl Eigenschaften. Klicken Sie alternativ dazu auf den Projektnamen und wählen Sie den Menübefehl Projekt | Eigenschaften.
3.Überprüfen Sie die Projekteinstellungen und ändern Sie sie gegebenenfalls. Stellen Sie v.a. sicher, dass die Zielsprache und das Ausgabeverzeichnis korrekt eingestellt wurden. Klicken Sie anschließend auf OK.
4.Klicken Sie im Menü Projekt auf den Befehl Code für das gesamte Projekt generieren.
Unabhängig von der im Dialogfeld Projekteigenschaften ausgewählten Sprache können Sie jederzeit Projektcode in einer anderen Sprache generieren, indem Sie den Menübefehl Projekt | Code generieren in | <Sprache> auswählen.
Der Fortschritt und das Ergebnis der Codegenerierung werden im Fenster "Meldungen" angezeigt. Standardmäßig ist der Name der generierten Applikation mit dem Projektnamen identisch. Wenn der Projektname Leerzeichen enthält, werden diese im generierten Code in Unterstriche konvertiert. Standardmäßig wird Code im selben Verzeichnis wie das MapForce-Projekt generiert, nämlich im untergeordneten Ausgabeverzeichnis.
Sie können das Ausgabeverzeichnis und/oder den Namen des Projekts im Dialogfeld Projekteigenschaften ändern. Wenn Ihr MapForce-Projekt Ordner enthält, können Sie die Codegenerierungseinstellungen für die einzelnen Ordner konfigurieren. Klicken Sie mit der rechten Maustaste auf den gewünschten Ordner und wählen Sie im Kontextmenü den Befehl Eigenschaften. Andernfalls erben alle Projektordner die auf der obersten Ebene definierten Einstellungen. Nähere Informationen zu Projekten und Einstellungen und Verfahren im Zusammenhang mit Projekten finden Sie unter Projekte.
Sprachspezifische Informationen
In diesem Unterabschnitt werden die Besonderheiten der Generierung von Code in verschiedenen Transformationssprachen beschrieben. Des Weiteren wird hier erläutert, wie der generierte C++-, C#- und Java-Code gebaut und die Applikation ausgeführt wird. Sie können auch Code in XSLT 1-3 und XQuery generieren. Nähere Informationen dazu finden Sie unter Codegenerierung.
C++- und C#-Code
C++- und C#-Code wird nach demselben Prinzip generiert, gebaut und ausgeführt: In den folgenden Unterabschnitten werden die einzelnen Verfahren in groben Zügen beschrieben.
Nachdem Sie C++- oder C#-Code generiert haben, enthält die Lösung die folgenden Komponenten:
•Projektmappe (.sln) und Projektdateien (.vcxproj für C++ und .csproj für C#), die in Visual Studio geöffnet werden können
•eine Reihe von für das Mapping erforderlichen Altova-signierten Bibliotheken (alle mit dem Präfix Altova)
•das Hauptmapping-Projekt (standardmäßig mit dem Namen Mapping), das die Mapping-Applikation und die davon abhängigen Dateien enthält
Beachten Sie, dass Sie den Standardnamen des Hauptmappingprojekts im Dialogfeld Mapping-Einstellungen ändern können.
Nachdem Sie den C++/C#-Code generiert haben, wird in den nächsten Schritten der Code gebaut und die Applikation ausgeführt. Der Code kann auf zwei Arten gebaut werden: (i) in Visual Studio und (ii) über die Befehlszeile (nähere Informationen siehe unten). Beachten Sie, dass der entsprechende SDK und eine kompatible Visual Studio-Version installiert sein müssen, um C#-Code bauen zu können. Informationen dazu, welches Download-Paket Sie für Ihr Betriebssystem und Ihre Plattform benötigen, finden Sie auf der Microsoft Website.
Bauen von generiertem Code in Visual Studio
Um den generierten C++/C#-Code mit Build zu bauen, gehen Sie folgendermaßen vor:
1.Öffnen Sie die generierte Projektmappendatei (.sln) in Visual Studio. Standardmäßig lautet der Name der Lösungsdatei Mapping.sln. Die Datei befindet sich relativ zu dem Verzeichnis, in dem sich der generierte Code befindet, im Unterverzeichnis Mapping.
2.Wählen Sie die gewünschte Build-Konfiguration aus (z.B. Debug). Beachten Sie, dass bei C++ nur Unicode Builds alle Unicode-Zeichen in XML und anderen Dateien unterstützen. In Nicht-Unicode-Builds wird die lokale Codepage Ihres Windows-Systems verwendet.
3.Klicken Sie im Menü Build auf Build Solution.
Durch das Bauen des Codes werden eine Befehlszeilenapplikation namens Mapping.exe und die dazugehörigen Dateien erstellt. Die Mapping-Applikation befindet sich relativ zur .sln-Datei in einem der Unterverzeichnisse. Der Name des Unterverzeichnisses hängt von der gewählten Build-Konfiguration ab: z.B. Debug (C++), bin\Debug (C#).
Bauen von generiertem Code über die Befehlszeile
Um den generierten Code über die Befehlszeile zu bauen, wechseln Sie in das Verzeichnis mit dem generierten Code und starten Sie den folgenden Befehl:
devenv Mapping.sln /Build "Debug|AnyCPU" /Project Mapping
Dieser Befehl ruft Visual Studio auf und definiert den Namen der zu bauenden Lösungsdatei (in unserem Fall Mapping.sln), die gewünschte Konfiguration (Debug und any CPU in unserem Fall) und den Namen des Projekts, zu dem die Lösungsdatei gehört (Mapping). Durch das Bauen des Codes werden eine Befehlszeilenapplikation namens Mapping.exe und die dazugehörigen Dateien erstellt. Die Mapping-Applikation befindet sich relativ zur .sln-Datei in einem der Unterverzeichnisse. Der Name des Unterverzeichnisses hängt von der gewählten Build-Konfiguration ab: z.B. Debug (C++), bin\Debug (C#).
Anmerkungen zum Bauen von C#-Code
Anstatt Visual Studio aufzurufen, können Sie auch .NET aufrufen, um den generierten C#-Code zu bauen. Gehen Sie folgendermaßen vor:
1.Stellen Sie sicher, dass im Dialogfeld Optionen im Abschnitt Code-Generierung (Menü Extras) die richtige Zielplattform ausgewählt ist. Nähere Informationen dazu finden Sie unter Code-Generierung.
2.Wenn als Ziel .NET/.NET Core ausgewählt ist, konfigurieren Sie die Umgebungsvariablen PATH und DOTNET_ROOT, damit sie auf den Ordner verweisen, in dem .NET/.NET Core installiert ist. Dadurch werden mögliche Probleme mit CLI-Befehlen vermieden.
3.Öffnen Sie ein Eingabeaufforderungsfenster und wechseln Sie in das Verzeichnis, in dem sich der generierte Code befindet.
4.Führen Sie den folgenden Befehl aus:
dotnet build Mapping\Mapping.sln --configuration Release
Dier Befehl ruft .NET auf, um die Lösungsdatei Mapping.sln mit der Konfiguration Release zu bauen und erstellt im Zielordner eine ausführbare Datei namens Mapping.exe mit den dazugehörigen Dateien. Der Name des Zielordners hängt von der ausgewählten Konfiguration und der verwendeten .NET-Version ab. In unserem Beispiel wird die ausführbare Datei im Ordner bin\Release\net8.0 gespeichert.
Ausführen der Applikation
Nachdem Sie den Code direkt in Visual Studio oder über die Befehlszeile gebaut haben, können Sie fortfahren und die Applikation ausführen. Um die Applikation auszuführen, doppelklicken Sie auf Mapping.exe oder rufen Sie die ausführbare Datei über die Befehlszeile auf. Nach Ausführung der ausführbaren Datei wird das Ergebnis der Mapping-Transformation im Zielordner gespeichert (standardmäßig ist dies der Ordner, in dem die ausführbare Datei gespeichert ist).
Wenn Sie den generierten Code in Linux bauen, erhält die generierte ausführbare Datei den Namen Mapping ohne Erweiterung. Um die ausführbare Datei starten zu können, müssen Sie eventuell den folgenden Befehl verwenden:
./Mapping
Java-Code
Nachdem Sie Java-Code generiert haben, enthält das Java-Projekt die folgenden Komponenten:
•eine Reihe von für das Mapping erforderlichen Altova-signierten Java-Bibliotheken (alle mit dem Präfix com.Altova).
•das com.mapforce-Paket, das die Mapping-Applikation und die davon abhängigen Dateien enthält. Die beiden wichtigsten Dateien in diesem Paket sind die folgenden Dateien, in denen die Eintrittspunkte der Applikation definiert sind:
odie Java Mapping-Applikation als Dialog-Applikation (MappingApplication.java).
odie Java Mapping-Applikation als Konsolenapplikation (MappingConsole.java).
•eine build.xml-Datei, die Sie mit Apache Ant ausführen können, um das Projekt zu kompilieren und JAR-Dateien zu generieren.
Die Standardnamen der Mapping-Applikation und die davon abhängigen Dateien im Paket com.mapforce haben das Präfix Mapping. Sie können den Namen sowie andere Einstellungen bei Bedarf im Dialogfeld Mapping-Einstellungen ändern.
Nachdem Sie Java-Code generiert haben, wird in den nächsten Schritten der Code gebaut und ausgeführt. Es gibt zwei grundlegende Methoden, um den generierten Code zu bauen und die Applikation auszuführen: (i) in Eclipse und (ii) über die Befehlszeile mit Apache Ant. In den folgenden Unterabschnitten werden die einzelnen Verfahren in groben Zügen beschrieben.
Bauen des generierten Codes und Ausführung der Applikation in Eclipse
Bei dieser Methode wird nach dem Eclipse-Ablauf vorgegangen. Beachten Sie dabei die folgenden Voraussetzungen:
•Java Development Kit (JDK), Eclipse sowie Apache Ant müssen auf Ihrem System installiert sein. Eclipse enthält normalerweise eine darin verpackte Version von Ant. Sie können Ant aber auch separat installieren.
•Um Eclipse mit OpenJDK auszuführen, muss die PATH-Umgebungsvariable normalerweise den Pfad zum JDK-bin-Verzeichnis (z.B: C:\Java\jdk-11.0.1\bin) enthalten.
•Die JAVA_HOME-Umgebungsvariable muss auf das JDK-Installationsverzeichnis verweisen.
•Die ANT_HOME-Umgebungsvariable muss auf das Apache Ant-Installationsverzeichnis verweisen.
Nachdem der Java-Code nun generiert wurde, wird er im nächsten Schritt in Eclipse importiert. Gehen Sie folgendermaßen vor:
1.Klicken Sie im Menü File auf Import und anschließend auf General | Existing Projects into Workspace.
2.Klicken Sie auf Next.
3.Geben Sie den Pfad zum generierten Code an und klicken Sie auf Finish. Das mit MapForce erstellte Java-Projekt steht nun in der Package Explorer-Ansicht zur Verfügung. Wenn Sie die Package Explorer-Ansicht nicht sehen, wählen Sie den Menübefehl Window | Show View | Package Explorer, um die Ansicht anzuzeigen.
Beachten Sie, dass der Code standardmäßig jedes Mal, wenn einer Änderung erkannt wird, automatisch gebaut wird. Sie können diese Funktionalität auch deaktivieren und den Code nur bei Bedarf bauen (nähere Informationen dazu finden Sie in der Eclipse-Dokumentation).
Nachdem Sie Ihren Code importiert und gebaut haben, kann die Applikation im nächsten Schritt ausgeführt werden. In diesem Kapitel werden einige mögliche Varianten behandelt, wie eine Applikation ausgeführt werden kann.
Methode 1: Ausführen des Projekts als Applikation
Mit dieser Methode können Sie Ihr Java-Projekt als GUI-Applikation ausführen. Gehen Sie folgendermaßen vor:
1.Klicken Sie in der Package Explorer-Ansicht von Eclipse mit der rechten Maustaste im Paket com.mapforce auf die Datei MappingApplication.java.
2.Wählen Sie im Kontextmenü den Befehl Run As | Java application.
3.Klicken Sie im daraufhin angezeigten MapForce-Applikationsfenster auf Start, um das Mapping auszuführen.
Methode 2: Ausführen des Projekts als Konsolenapplikation
Mit dieser Methode können Sie Ihr Java-Projekt als Konsolenapplikation (command-line) ausführen. Gehen Sie folgendermaßen vor:
1.Klicken Sie in der Package Explorer-Ansicht von Eclipse mit der rechten Maustaste im Paket com.mapforce auf die Datei MappingConsole.java.
2.Wählen Sie im Kontextmenü den Befehl Run As | Java application.
Unabhängig von der gewählten Methode führt die Java-Applikation bei ihrer Ausführung die Mapping-Transformation aus und generiert im Zielordner eine oder mehrere Ausgabedateien.
Bauen des generierten Codes und Ausführung der Applikation über die Befehlszeile
Um Ihren generierten Code über die Befehlszeile bauen und ausführen zu können, müssen Sie die folgenden Komponenten installiert und die folgenden Umgebungsvariablen definiert haben:
•Java Development Kit (JDK) sowie Apache Ant müssen auf Ihrem System installiert sein.
•Der Pfad zum Ant-Verzeichnis bin (z.B. C:\apache-ant-1.10.5\bin) sollte zur PATH-Umgebungsvariablen hinzugefügt werden. Dadurch kann Ant ausgeführt werden, ohne dass Sie in der Befehlszeile den vollständigen Pfad zur ausführbaren Datei eingeben müssen.
•Die JAVA_HOME-Umgebungsvariable muss auf das JDK-Installationsverzeichnis verweisen.
•Die ANT_HOME-Umgebungsvariable muss auf das Apache Ant-Installationsverzeichnis verweisen.
Um den generierten Code mit Apache Ant zu bauen, gehen Sie folgendermaßen vor:
1.Öffnen Sie ein Befehlszeilenfenster und wechseln Sie in das Verzeichnis, in dem der generierte Code einschließlich der Build-Datei (build.xml) gespeichert ist.
2.Führen Sie den folgenden Befehl aus:
ant jar
Mit diesem Befehl wird der generierte Code gebaut und eine JAR-Datei (standardmäßig mit dem Namen Mapping.jar) erstellt. In die JAR-Datei sollen die Java .class-Dateien und die dazugehörigen Metadaten und Ressourcen verpackt werden. In unserem Fall soll das JAR-Archiv als ausführbares Java-Programm verwendet werden; die Manifest-Datei des Archivs enthält daher den Eintrittspunkt der Applikation (standardmäßig com.mapforce.MappingConsole).
Um die Java-Applikation zu starten, führen Sie im Verzeichnis, in dem sich das JAR-Archiv befindet, den folgenden Befehl aus:
java com.mapforce.MappingConsole Mapping.jar
Dieser Befehl startet die Java Virtual Machine, ruft die Hauptklasse com.mapforce.MappingConsole, die auf den Eintrittspunkt der Java-Applikation verweist, auf und führt das in der JAR-Datei enthaltene Programm namens Mapping.jar aus. Dadurch führt die Java-Applikation die Mapping-Transformation aus und generiert im Zielordner eine oder mehrere Ausgabedateien. Falls Sie die Applikation als GUI-Applikation starten möchten, übergeben Sie den folgenden Wert für das Argument der Hauptklasse: com.mapforce.MappingApplication. Daraufhin wird ein Popup-Fenster geöffnet, über das Sie die Mapping-Transformation starten können:
Vermeiden möglicher Probleme aufgrund von zu wenig Arbeitsspeicher
Es kommt vor, dass bei komplexen Mappings mit großen Schemas eine so große Menge von Code generiert wird, dass es bei der Kompilierung in Ant zu einem java.lang.OutofMemory-Ausnahmeereignis kommt. Um solche Probleme zu vermeiden, gehen Sie folgendermaßen vor:
1.Fügen Sie die Umgebungsvariable ANT_OPTS hinzu. Damit werden bestimmte Ant-Optionen festgelegt, wie z.B. wie viel Arbeitsspeicher dem Compiler zur Verfügung steht. Sie können den Wert folgendermaßen definieren: -server -Xmx512m -Xms512m.
2.Um sicherzustellen, dass der Compiler und der generierte Code im selben Prozess wie Ant ausgeführt werden, ändern Sie das Attribut fork in der Datei build.xml in false.
Je nach verfügbarem Arbeitsspeicher auf Ihrem Computer und je nach Projektgröße müssen Sie diese Werte eventuell anpassen. Nähere Informationen finden Sie in der Java VM-Dokumentation.
Bei der Ausführung des ant jar-Befehls wird eventuell eine Fehlermeldung angezeigt, dass "[...] das Archiv mehr als 65535 Einheiten enthält". Damit diese Fehlermeldung nicht auftritt, wird empfohlen, Versionen ab Ant 1.9 zu verwenden und in build.xml zum Element <jar> zip64mode="as-needed" hinzuzufügen.
Vermeiden potenzieller Probleme mit JDBC-Verbindungen
Wenn Sie Java-Code anhand eines Mappings generiert haben, in dem die Verbindung zu einer Datenbank über JDBC hergestellt wurde, müssen Sie eventuell den JDBC-Treiber als Classpath-Eintrag zur aktuellen Konfiguration hinzufügen. Andernfalls könnte die Ausführung der Applikation zu einem Fehler führen. Nähere Informationen dazu finden Sie unter Datenbanken.