How-to: Wie kann man die Webservices von webPDF 7 verwenden

(Dieses How-to wurde für webPDF 7 und folgende Versionen erstellt. Die Nutzung der Webservice-Schnittstellen hat sich mit dieser Version grundlegend geändert. Für webPDF 6 finden Sie dieses Tutorial unter https://www.webpdf.de/blog/how-to-wie-kann-man-die-webservices-von-webpdf-verwenden/)

Webservices von webPDF 7

In diesem Beispiel geht es darum, zu zeigen, wie man die Webservices von webPDF nutzen kann. In diesem Beispiel wird der Webservice „Converter“ benutzt, eine ausgewählte Datei in ein PDF-Dokument zu konvertieren.  Zur Ansteuerung des Webservice wird die Programmiersprache Java genutzt. Um dieses Beispiel auf Ihrem PC nachzuvollziehen benötigen Sie ein lokal installiertes webPDF, ein JDK mit der Version 1.7 oder höher und die IDE IntelliJ (die Community-Edition genügt für diesen Zweck).

Einrichtung des Projektes mit IntelliJ

Nachdem Sie die Softwareumgebung eingerichtet haben, beginnen Sie mit dem Anlegen des Java Projektes in IntelliJ. Nach dem Starten klicken Sie in der Startansicht auf ‚Create new Project‚ oder wenn Sie bereits Projekte mit IntelliJ geöffnet hatten in der Menüleiste der Hauptansicht auf ‚File‚->‘New‚->‘Project…‚

Danach wählen Sie ‚Java‚ als Projekttyp(1)  aus und wählen Ihr installiertes JDK aus, das Sie vermutlich noch mit ‚New …‚(2) hinzufügen müssen (dazu müssen Sie den Hauptordner des JDKs in Ihrem Dateisystem auswählen).

Klicken Sie danach auf ‚Next‚. Im nächsten Dialog werden Sie gefragt ob Sie ein Template zum erstellen Ihres Projektes nutzen wollen. Wählen Sie das Template ‚Command Line App‚ und klicken Sie auf ‚Next‚.

Im nächsten Dialog geben Sie alle Angaben ein wie es auf dem folgendem Screenshot zu sehen sind und klicken auf ‚Finish‚.

Danach öffnet IntelliJ, nach der Rückfrage ob das Verzeichnis angelegt werden darf, das erstellte Projekt. Öffnen Sie in der Menüleiste noch die Projektansicht über ‚View‚->‚Tool Windows‚->‘Project‚. Die Ansicht müsste nun ähnlich dem folgenden Screenshot aussehen.

Das Projekt für IntelliJ ist eingerichtet.

Erstellung der benötigten Proxy Klassen mit wsimport

Der anzusprechende Webservice arbeitet mit dem SOAP-Protokoll. Um diesen zu nutzen, benötigen wir die passenden Proxy Klassen(„client stubs“). Diese werden Sie in diesem Schritt generieren.

Öffnen Sie den Projektordner in IntelliJ und klicken Sie per Rechtsklick auf den „src“-Ordner(1).

In der geöffneten Auswahl wählen Sie „Copy Path“. Nun öffnen Sie die Eingabeaufforderung und geben „cd “ ein und fügen den Pfad aus der Zwischenablage dahinter ein. Drücken Sie die Eingabetaste und Sie sind im Source-Ordner Ihres Projektes. Dort fügen Sie den folgenden  Befehl  ein und führen ihn aus(2)(sollte eine Fehlermeldung angezeigt werden ist Ihr JDK vermutlich nicht in den Umgebungsvariablen eingetragen).

Bemerkung:
Wenn Sie webPDF nicht auf dem vorgegebenen Port(8080) installiert haben, müssen Sie dies in dieser und in zukünftigen genutzten URLs beachten und anpassen

wsimport -Xnocompile -s . http://localhost:8080/webPDF/soap/converter?wsdl -extension

Danach können Sie direkt im Package „de.webpdf.schema._1_0“ die erstellten Proxy Klassen sehen(3).

Die benötigten Proxy Klassen wurden erstellt.

Umsetzung der Webservice-Anfrage

Der gesamte Beispielcode wird, in die bereits erstellte, „main“-Methode der „Main“- Klasse eingefügt. Beginnen Sie nun mit dem Anlegen des Methoden-Inhalts.

Bemerkung:
Wenn Sie den nachfolgenden Code eingeben, dann werden die unbekannten Klassen mit roter Schrift gekennzeichnet. Um diese Klasse mit entsprechenden „Import-Anweisungen aufzulösen, stellen sie den Cursor auf die Klasse und drücken sie „Strg+Leertaste“ (wenn mehr Imports möglich sind) bzw. „Alt+Enter“ (wenn nur ein Import möglich ist)

URL converterUrl;
try {
    //wsdl URL wenn Sie ein anderes Port nutzen müssen Sie die URL anpassen
    converterUrl = new URL("https://localhost:8080/webPDF/soap/converter?wsdl");
} catch (MalformedURLException ex) {
    System.err.println(ex.getMessage());
    return;
}

Hier wird ein URL-Objekt initialisiert. Da der Konstruktor eine Exception werfen kann, findet die Initialisierung in einem Try-Catch-Block statt, der beim Auftreten einer MalformedURLException diese fängt und eine Nachricht ausgibt. Außerdem würde in diesem Fall das Programm gleich mit „return“ beendet, da die weitere Ausführung ohne das URL-Objekt sinnlos wäre.

//Behälter für alle Parameter(Webservice spezifische und allgemeine - Siehe Doku)
Operation converterOperation = new Operation();
//Behälter für Webservice spezifische Parameter(Muss eingefügt werden!)
converterOperation.setConverter(new ConverterType());

ConverterService converterService = new ConverterService(converterUrl);

Converter converter = converterService.getConverterPort();

Als erstes wird ein Operation-Element initialisiert, welches der Container für alle webPDF-Parameter ist. Danach wird ein ConverterType Element erzeugt und zur Operation hinzugefügt. Dies ist die minimale Angabe die zum Nutzen des Converter Webservices benötigt wird. Mit der URL wird ein Objekt vom Typ ConverterService initialisiert. Dies beinhaltet alle Ports, oder aktueller Endpoints, des Converter-Webservices. Danach wird der Endpoint in Form eines Converter-Objektes initialisiert, indem es vom Service abgefragt wird. Endpoints stellen die finale Kommunikationsschnittstelle dar.

//Zu konvertierende Datei
File inputFile = new File("src/de/webpdf/schema/_1_0/soap/converter/Converter.java");

//Ausführung des Converter-Webservices mit einem Datahandler
DataHandler inputHandler = new DataHandler(new FileDataSource(inputFile));
DataHandler resultHandler = null;
try {
    resultHandler = converter.execute(converterOperation, inputHandler, null);
    try (FileOutputStream fos = new FileOutputStream(new File("./ConverterFileContentResult.pdf"))) {
        resultHandler.writeTo(fos);
    }
} catch (WebserviceException | IOException ex) {
    System.err.println(ex.getMessage());
    return;
}

Hier werden 2 DataHandler-Objekte initialisiert, eines übernimmt ein File Objekt das Interface de.webpdf.schema._1_0.soap.converter.Converter in Ihren src-Ordner verweist, welches konvertiert werden soll und der andere bekommt in dem Try-Catch-Block das Ergebnis der Konvertierung zugewiesen. Die Konvertierung wird ausgeführt, indem beim Endpoint (die Variable ‚converter‘ vom Typ Converter) die Methode ‚execute‘ aufgerufen wird. Dabei wird als Parameter das Operation-Object converterOperation und der DataHandler inputHandler mit der zu konvertierenden Datei übergeben. Beim dritten möglichen Parameter wird der Wert null übergeben, hier könnte alternativ zum DataHandler eine URL übergeben werden die auf die zu konvertierende Datei verweist. Das Ergebnis wird per FileOutputStream auf Ihrem Rechner gespeichert. Die Konvertierung ist an dieser Stelle durchgeführt.

//Ausführung des Converter-Webservices mit einer URL
resultHandler = null;
try {
    resultHandler = converter.execute(converterOperation, null, inputFile.toURI().toURL().toString());
    try (FileOutputStream fos = new FileOutputStream(new File("./ConverterFileUrlResult.pdf"))) {
        resultHandler.writeTo(fos);
    }
} catch (WebserviceException | IOException ex) {
    System.err.println(ex.getMessage());
}

Dieser Code ist optional und tut, dasselbe wie der zuvor beschriebene Code mit dem Unterschied, das eine URL anstatt eines DataHandlers für die zu konvertierende Datei genutzt wird.

Führen Sie das Programm nun aus.

Sie haben eine JAVA-Datei über einen webPDF Webservice zu einer PDF-Datei konvertiert.

Herzlichen Glückwunsch!

Anhang:
Benötigte Importe für die Klasse:

import de.webpdf.schema._1_0.operation.ConverterType;
import de.webpdf.schema._1_0.operation.Operation;
import de.webpdf.schema._1_0.soap.converter.Converter;
import de.webpdf.schema._1_0.soap.converter.ConverterService;
import de.webpdf.schema._1_0.soap.converter.WebserviceException;

import javax.activation.DataHandler;
import javax.activation.FileDataSource;
import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.net.MalformedURLException;
import java.net.URL;

Hier heht es zu Teil 2 und 3 unserer Technik-Reihe Webservices..