Nutzung der SOAP Schnittstelle mittels webPDF wsclient

In diesem Beitrag möchten wir Ihnen zeigen, wie Sie die „webPDF wsclient“-Bibliothek (kurz „wsclient“) in Java nutzen können, um die webPDF Webservices über die SOAP-Schnittstelle anzusprechen. Hierfür ist es hilfreich, wenn Sie den Beitrag „Die webPDF wsclient Bibliothek“ bereits gelesen haben.

Einen Beitrag, der die Nutzung der REST-Schnittstelle erläutert, finden sie hier:

Nutzung der REST Schnittstelle mittels webPDF wsclient

Der erste SOAP Webserviceaufruf

Im folgenden Beispiel möchten wir uns mit dem grundsätzlichen Aufruf eines webPDF SOAP Webservices über „wsclient“ beschäftigen, bevor wir in weiteren Beiträgen die einzelnen Webservices selbst besprechen werden.

Der Aufruf sämtlicher SOAP Webservices mittels „wsclient“ erfolgt nach dem hier vorgestellten Muster. In diesem Beispiel möchten wir exemplarisch den „Converter“ Webservice aufrufen, der aber lediglich als Platzhalter für alle anderen webPDF Webservices dienen soll. Sämtliche der hier genutzten Klassen werden über „wsclient“ zur Verfügung gestellt, ohne dass weitere Vorarbeiten nötig wären.

Verbindungsherstellung über SoapSession

Zunächst muss die Verbindung zum webPDF Server hergestellt und eine Session erzeugt werden, hierfür Instanziieren wir ein SoapSession Objekt über die SessionFactory. Für die Instanziierung wählen wir entsprechend das WebServiceProtocol SOAP und übergeben die URL (und den Port) auf dem unser webPDF Server erreichbar ist.

SoapSession session = SessionFactory.createInstance(
   WebServiceProtocol.SOAP,
   new URL("https://localhost:8080/webPDF/")
);

Bitte beachten Sie, dass diese Session am Ende wieder mit „session.close()“ geschlossen wird bzw. ab Java 7 in ein „try-with-resources“ Statement eingebunden wird.

Wahl von Quell- und Zieldokument

Rufen wir einen webPDF Webservice auf, so möchten wir in der Regel ein bestimmtes Quelldokument verarbeiten und damit ein Zieldokument erzeugen. Die Anwahl von Quell- und Zieldokument erfolgen über ein SoapDocument Objekt. Wir übergeben diesem sowohl Quelle, als auch Ziel im Konstruktor, der uns zwei Varianten anbietet.

Entweder übergeben wir als Quelldokument direkt eine Ressource, die über eine URI auffindbar ist und für das Zieldokument eine Datei, in die das Arbeitsergebnis geschrieben werden soll.

Oder wir übergeben als Quelldokument einen InputStream, der das zu verarbeitende Dokument hält und einen OutputStream, in den das Arbeitsergebnis geschrieben werden soll.

In diesem Beispiel gehen wir davon aus, uns liegt das Quelldokument als Datei vor und wir möchten das Arbeitsergebnis in eine bestimmte Datei schreiben.

SoapDocument soapDocument = new SoapDocument(
   new File("Pfad des Quelldokuments").toURI(),
   new File("Pfad des Zieldokuments")
)

Beachten Sie auch hierbei, dass in jedem Fall das SoapDocument Objekt am Ende geschlossen werden sollte.

Wahl und Konfiguration des Webservices

Den Aufruf des gewünschten Webservices bereiten wir mit Hilfe der WebServiceFactory vor. Diese gestattet die Auswahl des Webservices mittels der Enumeration WebServiceType und fordert von uns das bereits erzeugte SoapSession Objekt.

In unserem Beispiel wählen wir hier folglich den WebServiceType.CONVERTER.

ConverterWebService converterWebService =
   WebServiceFactory.createInstance(
   session, WebServiceType.CONVERTER
);

Als nächstes müssen unserem Webserviceaufruf Quell- und Zieldokument zur Verfügung gestellt werden, was wir über einen entsprechenden Setter tun, da wir auch das hierfür erforderliche SoapDocument Objekt bereits erzeugt haben.

converterWebService.setDocument(soapDocument);

Das Letzte was unserem Aufruf noch fehlt ist die Parametrisierung des Webserviceaufrufs. Diese wird gebündelt in einem Objekt abgelegt, das über die Methode getOperation() an unserer SoapSession abrufbar ist. Der Typ dieses Objekts entspricht unserem gewählten Webservice und stellt uns auch nur dessen relevante Parameter für Änderung und Abruf zur Verfügung.

Die Parameter, die wir hier übergeben, beeinflussen direkt das Ergebnis und die Durchführung der Operation, die wir auslösen wollen. Also beispielsweise die Qualität der Bilder des Ergebnisdokuments. Welche Parameter dies im Einzelnen sind hängt vom jeweiligen Webservice ab und können Sie der webPDF Dokumentation entnehmen.

Da wir den Converter aber in einem späteren Beitrag genauer besprechen wollen, ist für uns hier zunächst nur relevant, dass wir sämtliche relevanten Parameter an diesem Objekt setzen können. Beispielsweise konfigurieren wir folgende beiden Parameter:

converterWebService.getOperation().setJpegQuality(100);
converterWebService.getOperation().setDpi(300);

Ausführung, Auswertung und Abmeldung

Wir können nun schließlich über Aufruf der Methode process() die Operation ausführen. War die Ausführung erfolgreich, so wird das Arbeitsergebnis direkt in das im SOAPDocument gewählte Ziel geschrieben.

converterWebService.process();

Trat ein Fehler während der Ausführung auf, so können (müssen) wir diesen als ResultException in einem catch Block fangen und erhalten über diese gefangene Exception Zugriff auf die wsclient Fehlernummer und (falls vorhanden) den zu Grunde liegenden Fehler auf Seiten des webPDF Servers.

Das Ergebnis

Insgesamt ergibt sich also folgendes Ergebnis:

try (
    // Aufbau einer Session mit dem webPDF Server(hier SOAP):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Bereit stellen des Dokuments, das verarbeitet werden soll
    // und der Datei, in die das Ergebnis geschrieben werden soll:
    SoapDocument soapDocument = new SoapDocument(
        new File("Pfad des Quelldokuments").toURI(),
        new File("Pfad des Zieldokuments")
    )
) {
    // Wahl des Webservices über eine Factory:
    ConverterWebService converterWebService =
        WebServiceFactory.createInstance(
            session, WebServiceType.CONVERTER
        );
    converterWebService.setDocument(soapDocument);
    // Objektorientierte Parametrisierung des Aufrufs:
    converterWebService.getOperation().setJpegQuality(100);
    converterWebService.getOperation().setDpi(300);
    // Ausführung.
    converterWebService.process();
} catch (ResultException ex) {
    // Zur Auswertung möglicher aufgetretener Fehler, stellt ihnen die
    // wsclient Bibliothek entsprechende Methoden zur Verfügung:
    int webPDFErrorCode = ex.getResult().getCode();
    Exception exception = ex.getResult().getException();
}

Die Parameter der einzelnen Webservices werden in späteren Beiträgen genauer besprochen, insgesamt finden Sie eine Dokumentation aller webPDF Parameter in unserer Parameter Dokumentation.

Eine Dokumentation der Fehlernummern der webPDF wsclient Bibliothek finden Sie hier: https://github.com/softvision-dev/webpdf-wsclient/wiki/Error-Codes