Nutzung der REST 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 REST-Schnittstelle anzusprechen. Hierfür ist es hilfreich, wenn Sie den Beitrag „Die webPDF wsclient Bibliothek“ bereits gelesen haben.

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

Nutzung der SOAP Schnittstelle mittels webPDF wsclient

Der erste REST Webserviceaufruf

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

Der Aufruf sämtlicher REST 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 RestSession

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

RestSession session = SessionFactory.createInstance(
   WebServiceProtocol.REST,
   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.

Login und Wahl des Quelldokuments

Rufen wir einen webPDF Webservice auf, so möchten wir in der Regel ein bestimmtes Quelldokument verarbeiten und damit ein Zieldokument erzeugen. Zunächst müssen wir hierfür dem Server das Quelldokument bekannt machen und dieses für die Verarbeitung zur Verfügung stellen.

Wir verbinden uns zunächst mit dem webPDF Server über Aufruf der Methode login() an unserem RestSession Objekt.

Im nächsten Schritt rufen wir über die Methode getDocumentManager() an unserer RestSession das DocumentManager Objekt ab und lösen schließlich an diesem mittels der Methode uploadDocument() den Upload unserer Quelldatei auf den webPDF Server aus.

Das hierbei erzeugte RestDocument handhabt im weiteren Verlauf sämtliche Zugriffe auf das Dokument, das wir soeben hoch geladen haben.

session.login();
RestDocument sourceDocument =
    session.getDocumentManager()
        .uploadDocument(
            new File("Pfad des Quelldokuments")
        );

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 RestSession Objekt.

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

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

Als nächstes muss unserem Webserviceaufruf das Quelldokument bekannt gemacht werden, dessen Upload wir im Schritt davor bereits vorgenommen haben.

converterWebService.setDocument(sourceDocument);

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 RestSession 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 uns das Arbeitsergebnis in Form eines RestDocument Objekts zurückgegeben.

Analog zum RestDocument, dass wir durch den Upload unseres Quelldokuments erzeugt haben verwaltet auch dieses den Zugriff auf ein Dokument, das auf dem webPDF Server liegt.

Um nun also unser Arbeitsergebnis auch tatsächlich zu erhalten, laden wir das Document über Aufruf der Methode downloadDocument() herunter und schreiben es in einen geeigneten OutputStream unserer Wahl (hier beispielsweise in eine Datei):

RestDocument resultDocument = converterWebService.process();
try (FileOutputStream outputStream =
         new FileOutputStream(new File("Pfad des Zieldokuments"))
) {
    session.getDocumentManager()
        .downloadDocument(resultDocument, outputStream);
}

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 REST Session mit dem webPDF Server:
    RestSession session = SessionFactory.createInstance(
        WebServiceProtocol.REST,
        new URL("https://localhost:8080/webPDF/")
    );
) {
    // Login am webPDF Server
    session.login();
    // Bereit stellen des Dokuments, das verarbeitet werden soll.
    RestDocument sourceDocument =
        //Abruf des DocumentManagers an der Session.
        session.getDocumentManager()
            //Upload des Quelldokuments auf den webPDF Server
            .uploadDocument(
                new File("Pfad des Quelldokuments")
            );
    // Wahl des Webservices über eine Factory:
    ConverterRestWebService converterWebService =
        WebServiceFactory.createInstance(
            session, WebServiceType.CONVERTER
        );
    converterWebService.setDocument(sourceDocument);
    // Objektorientierte Parametrisierung des Aufrufs:
    converterWebService.getOperation().setJpegQuality(100);
    converterWebService.getOperation().setDpi(300);
    // Ausführung und Abruf des Zieldokuments.
    RestDocument resultDocument = converterWebService.process();
    // Download unseres Arbeitsergebnisses
    try (FileOutputStream outputStream =
             new FileOutputStream(new File("Pfad des Zieldokuments"))
    ) {
        session.getDocumentManager()
            .downloadDocument(resultDocument, outputStream);
    }
} 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